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Preface 


Apple® File Exchange is an application for moving files between the Apple 
Macintosh® family of computers, the Apple II family of computers, and other 
computers. This manual describes how to write file conversion routines, known as 
translators, that are used by Apple File Exchange. 


Audience 

This manual is written both for professional programmers and for enthusiasts. It is 
distributed by the Apple Programmer’s and Developer’s Association (APDA). The 
manual assumes that readers are experienced Macintosh programmers and that they 
are familiar with the Macintosh User Interface Toolbox and Operating System routines 
described in Inside Macintosh. It also assumes that readers have used Apple File 
Exchange and are familiar with the program’s features. Readers who are not already 
experienced Apple File Exchange users should read the chapters on Apple File 
Exchange in the Macintosh Utilities User's Guide before using this manual. 


About this manual 

The manual is organized as follows: 

□ Chapter 1 introduces Apple File Exchange and translators. It also lists the hardware 
and software you’ll need to write translators. 

□ Chapter 2 tells how to design and write translators. It lists the tasks a translator must 
carry out and includes detailed reference information needed to implement a 
translator. 

□ Chapter 3 provides reference information for each of the messages sent from Apple 
File Exchange to translators. 

□ Chapter 4 provides reference information for the ProDOS® file system calls that 
can be made from translators. 

□ Chapter 5 provides reference information for the MS-DOS file system calls that can 
be made from translators. 

□ Appendix A lists Pascal conventions for character strings, parameter passing, and 
register assignments. These conventions must be observed by translators written in 
programming languages other than Pascal. 









□ Appendix B lists Apple File Exchange diagnostic messages that are available for use 
by translators. 

□ Appendix C provides an example of a translator. You can use this example as the 
starting point for a new translator. 

□ Appendix D describes the differences between the U.S. and international versions 
of Apple File Exchange. 

□ Appendix E lists the character transliterations performed by Apple File Exchange 
transliteration routines. 

At the end of the manual are a glossary and an index. Terms in the manual that are 

shown in boldface appear in the glossary. 


For more information 

You can find important related information in these manuals: 

□ The Macintosh Utilities User's Guide includes two chapters that describe Apple File 
Exchange. These chapters, “Apple File Exchange" and “Apple File Exchange: 
Advanced Features,” provide detailed information about using Apple File 
Exchange. You should be familiar with the information in these chapters before you 
begin writing translators. 

□ Volumes I-IV of Inside Macintosh are the primary sources of information about 
the Macintosh Operating System and User Interface Toolbox routines. It is 
especially important that you be familiar with the routines described in the File 
Manager chapter in Volume IV. 

□ The Macintosh Programmer's Workshop Pascal Reference describes the version 
of Pascal used in the examples. 

In addition, the Apple Programmer’s and Developer’s Association (APDA) is an 
excellent source of technical information for anyone interested in developing Apple- 
compatible products. Membership in the association allows you to purchase Apple 
technical documentation, programming tools, and utilities. For information on 
membership fees, available products, and prices, please contact 

APDA 

290 SW 43 Street 
Renton, WA 98055 
(206) 251-6548 
AppleLink: APDA 
MCI: 312-7449 
CompuServe #73527,27 
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Syntax notation used in this manual 


The following notation is used in descriptions of function and procedure calls: 


terminal 

(a group) 
[optional] 

repeated... 

a I b I c 


Plain text indicates an element that must be entered exactly as shown. If 
there are special symbols (for example, + or /), they must also be 
entered exactly as shown. 

Parentheses group together elements. 

Square brackets indicate that the enclosed element or elements are 
optional. 

Three ellipsis points (...) indicate that the preceding element (or the 
preceding group of elements within parentheses or brackets) can be 
repeated one or more times. 

Vertical bars separate elements in a group from which a single element 
must be chosen. The elements are often grouped within parentheses or 
brackets. 


Throughout the manual, the Courier typeface is used to show sample programs and 
elements that appear in programs. 
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Chapter 1 


Introduction 








In this chapter, you’ll be introduced to Apple File Exchange and learn the role 
translators play in converting files. In addition, you’ll find information about the 
hardware and software you’ll need to write translators. 


About Apple File Exchange 

Apple File Exchange is a Macintosh application that lets users 

□ copy files and directories from one file system to another 

□ convert files from one file format to another 

□ transliterate the characters in a file from one character set to another 

Apple File Exchange runs on any Macintosh that supports double-sided disks. It allows 
users to copy files between these file systems: 

□ Macintosh 

□ ProDOS 

□ MS-DOS 

For examples of what Apple File Exchange can do, see the chapters dealing with Apple 
File Exchange in the Macintosh Utilities User’s Guide. 


Advantages of Apple File Exchange 

For developers writing translation routines, Apple File Exchange has important 

advantages over other file conversion utilities: 

□ It performs batch translation of dissimilar files. Files of different types can be 
translated in a single operation. 

o It can move files between Macintosh disks, 800K ProDOS disks, and 5.25-inch 
MS-DOS disks. 

□ It can be used with AppleShare™ File Server software. 

□ It is generally available. A copy of Apple File Exchange is now included with every 
Macintosh and every drive card for Apple PC 5.25 drives. In addition, owners of 
earlier Macintosh personal computers can get Apple File Exchange as part of the 
Macintosh System Update Version 5.0. This update is a retail product that is 
available from Apple dealers. 

□ It provides a consistent, easy-to-use user interface for all translations. 

□ It provides a framework that allows quick development of new translation routines. 
Apple File Exchange handles the user interface and provides file system calls that 
are the same for all file systems. This frees developers to concentrate on the actual 
file conversion. 
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About translators 

A translator is a routine invoked by Apple File Exchange when it copies a file. These 
routines are used to convert a file from one format to another. As part of translation, 
translators may also transliterate a file, that is, convert the printable characters in 
the file to the equivalent characters in another character set. 

Although the Apple File Exchange application includes several built-in translators, 
most translators are produced by independent software publishers. The built-in 
translators perform a number of fundamental translations, such as converting text files 
from one file system to equivalent text files on another. All other translations are 
performed by translators that are separate from the Apple File Exchange application. 

All translators, with the exception of the fundamental translators built into Apple File 
Exchange, are kept in translator files in the Apple File Exchange folder. 


Hardware and software requirements 

To write a translator for Apple File Exchange, you’ll need 

□ hardware that can read both the source and destination files 

□ development software for the Macintosh 
These requirements are described below. 


Hardware requirements 

Table 1-1 lists the hardware required for writing translators. 

Table 1-1 

Hardware required for writing Apple File Exchange translators 

If the source 
or destination 

file system is The hardware required is 


Macintosh Macintosh with built-in 800K drive. 

ProDOS Macintosh with built-in 800K drive. (Apple File Exchange can only 

translate ProDOS files from 800K ProDOS disks. It cannot translate 
ProDOS files from 5.25-inch ProDOS disks.) 

MS-DOS Macintosh SE with Apple PC 5.25 Drive and Macintosh SE Bus PC 

Drive Card 

or 

Macintosh II with Apple PC 5.25 Drive and Macintosh n PC Drive 
Card. 
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This chapter provides information you need to design and write translators. It includes 
o an overview of the tasks translators perform 

□ reference information about translators 

□ examples of translators 

Before beginning work on a translator, you should first become familiar with the ways 
in which people use translators. The Apple File Exchange chapters in the Macintosh 
Utilities User's Guide describe the tasks users perform when translating a file. Read 
these chapters and, if you haven’t already, spend some time using Apple File 
Exchange before going on. 


What translators must do 

This section gives an overview of the tasks that translators perform: 

1. They respond to calls from Apple File Exchange. These calls request specific 
services or pass information to the translator. 

2. They call routines in Apple File Exchange to communicate information back to the 
user. 

3. They make file system calls to read and write files and to perform other file 
operations. 

4. When necessary, they call transliteration routines (TProcs) to convert the 
characters in a file to another character set. 

5. They determine if they can translate a particular file. 

6. They respond appropriately when moved to other Apple File Exchange menus. 

In addition, Apple File Exchange makes its own calls to file systems. Figure 2-1 

illustrates the calls that occur during Apple File Exchange operation. 



Figure 2-1 

Relationship between Apple File Exchange, translators, file systems, and TProcs 
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Handling Apple File Exchange messages 

The job of a translator is to respond to messages from Apple File Exchange. There is a 
single function for all calls to a translator, which is of the form 

FUNCTION Translate (Message : integer; 

VAR TranslateData : longint; 

Param : longint; Self : handle) : 
longint; 

The Message parameter determines the task the translator performs in response to a 
call. The tasks performed by translators include 

□ providing information on the current status of the translator 

□ determining if the translator can translate a particular file 

□ giving a file a new name 

□ translating a file 

Chapter 3, “Messages From Apple File Exchange to Translators,” provides complete 
information about each of the messages. 


Calling Apple File Exchange routines 

To communicate information back to Apple File Exchange and, in turn, to the user, a 
translator calls routines that are part of Apple File Exchange. These routines enable a 
translator to 

□ inform the user of the current status of a translation 

□ put a message in the User Log 

□ put a message in the User Log and, after all translations are complete, display a 
dialog box indicating that important information has been added to the User Log 

These routines are described in detail in the section “Calls From Translators to Apple 
File Exchange” later in this chapter. 
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Calling file systems 

To perform operations involving files, translators call file system routines. Apple 
File Exchange supports these file systems: 

□ Macintosh Hierarchical File System (HFS) 

□ ProDOS 

□ MS-DOS 

The operations performed by file system routines include 

□ opening, reading, and writing files 

a creating, renaming, and deleting files 

□ allocating memory for files 

a reading and changing file and volume information 

To perform operations involving file systems, translators use the function CallFS: 

FUNCTION CallFS (msg : integer; fsdata : Ptr; 

pb : Ptr; async : boolean; 
fsroutine : handle) : OSErr; 

CallFS provides a single, uniform interface to all the file systems supported by Apple 
File Exchange. The fsroutine and fsdata parameters select the file system, while the 
msg parameter indicates the operation to perform. 

Apple File Exchange file systems are stored as resources. The operations they perform 
parallel those provided by the Macintosh file system wherever possible. The section 
“Calls From Translators to File Systems’ 1 later in this chapter provides details about 
calls to file systems, while Chapters 4 and 5 describe the differences between file 
system calls and their HFS counterparts. 


Converting character sets 

When a translator moves a file containing text to a computer, file system, or 
application that uses a different character set, it must convert the representation of 
each character in the file to the representation used in another character set This 
process of converting characters is called transliteration. Here is an example: on a 
French member of the Apple n family, the character d is represented by the 
hexadecimal number 40, while on the Macintosh d is represented by the hexadecimal 
number 88. When moving the character d from a French Apple II to a Macintosh, a 
translator calls a transliteration routine that changes its representation from 40 
hexadecimal to 88 hexadecimal. 

To perform most transliterations, translators use transliteration resources known as 
TProcs that are provided with Apple File Exchange. Each international version of the 
Macintosh includes a set of TProcs, known as a TProc family, for transliterating files 
between different computers used in the same country. For example, the TProcs 
included with a French Macintosh transliterate files between French versions of the 
Macintosh, Apple II, and IBM PC, while the TProcs included with an Italian 
Macintosh transliterate files between Italian versions of the Macintosh, Apple II, and 
IBM PC. To perform transliterations for which there are no TProcs, such as 
transliterations from one language to another or transliterations of files that use 
special character sets, translators must provide their own transliteration procedures. 
For details about calling TProcs, see the section “Calls From Translators to 
Transliteration Routines” later in this chapter. 
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Recognizing files 

Another of the tasks a translator must perform is deciding whether it can translate a 
file. Depending on the file system and the type of file, this task can either be simple or 
quite involved: 

□ For translators that translate Macintosh files, recognizing a file usually involves no 
more than a look at the file type and creator for the file. 

o Translators that translate ProDOS files can often recognize a file by its file type and 
auxiliary file type. It may not, however, be as simple as this: because ProDOS has 
only 256 unique file types, applications may be forced to use the same file type for 
files with differing characteristics. 

□ Translators for MS-DOS files face a more difficult task. Because there are no file 
types built into MS-DOS, translators often have to read a file and analyze its 
structure before deciding whether they can translate it. 

When designing a translator, you must decide what acceptance criteria the translator 
will use. Choose the criteria carefully: translators that attempt to translate the wrong 
files can destroy information, while translators that fail to recognize the files they 
should are frustrating for users. When in doubt, the translator should open a file and 
quickly search for characteristics that are unique to the kind of file it can translate. This 
search should be quick and efficient. Translators should not take the time to perform a 
trial translation of the entire file. The example that follows illustrates the design of one 
recognition algorithm. 

An example: Recognizing MS-DOS SYLK files 

Symbolic Link (SYLK) is a format used to represent files created by Microsoft 
Multiplan and other applications. SYLK files are made up of ASCII characters. They 
include these components: 

□ Records are the fundamental building blocks of SYLK files. They begin with a one- 
or two-character record-type descriptor and end with a new-line separator. (On the 
Macintosh, a carriage-return character serves as the new-line separator. On other 
computers, a new-line separator may be a carriage-return character followed by a 
line-feed character.) 

□ Fields are contained within records. They can begin with an optional field-type 
descriptor consisting of a semicolon (;) followed by a single character. 

Like other MS-DOS files, MS-DOS SYLK files do not have an explicit file type. 
Although MS-DOS filenames can have identifying extensions, these extensions can be 
altered and may not accurately reflect the contents of a file. To recognize an MS-DOS 
SYLK file, a translator must open the file and check to see if the first record is a SYLK 
ID record. An ID record begins with a record-type descriptor consisting of the 
character I or i followed by D or d. The record contains the field descriptor ;P or ;p 
followed by the name of the program that produced the file. Like all SYLK records, the 
ID record must end with a new-line separator. (On the IBM PC, the new-line separator 
is a return character followed by a line feed.) If a file begins with this record, it is 
almost certain to be a SYLK file. 
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Handling moves to other menus 

Special-purpose translators—the translators that appear in the top part of translator 
menus—can be imported to other menus through the use of the Other Translations 
menu item. (Except in very rare cases, translators written by suppliers other than 
Apple will be special-purpose translators. Special-purpose translators are discussed in 
greater detail in the section “Translator Resources and Menus” later in this chapter.) 
Because special-purpose translators can be imported, they must be able to handle 
translations between other file systems when appropriate. Normally, any special- 
purpose translator should handle translations when the source or destination file 
systems are the same as either of the file systems in the original menu. For example, a 
translator from the ProDOS to Mac menu should work when imported to the ProDOS 
to ProDOS or Mac to Mac menus, but it need not work in the ProDOS to MS-DOS or 
MS-DOS to MS-DOS menus. 

Translators must never crash when imported to another menu. If a translator cannot 
translate files between the new menu’s two file systems, it must inform the user with an 
alert or an entry in the User Log. 


Designing a translator’s user interface 

The following sections provide guidelines for designing a translator’s user interface. 
For additional information, refer to “The Macintosh User Interface Guidelines” 
chapters in Volumes I and IV of Inside Macintosh. 


Remember your audience 

When you design a translator, consider the diversity of your audience: 

□ Many Apple File Exchange users will be using the Macintosh for the first time. 

□ Many Apple File Exchange users will normally use a computer other than the 
Macintosh. Apple File Exchange will often be the only Macintosh application they 
use, and they’ll be reluctant to learn more about the Macintosh than they have to. 

□ Others will be experienced Macintosh users, but they’ll be unfamiliar with the 
terminology used to describe ProDOS and MS-DOS files. 

□ Among the people who use a particular translator, some may know a great deal 
about the files they’re translating, while others may know nothing at all about the 
files or the application used to create them. 

The best advice is to keep a translator’s user interface simple, and to make as few 

assumptions about your audience as you can. 
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Selecting a name for a translator 

There are two points to remember when choosing a name for a translator: 

□ The name you choose for the translator resource is the name that appears in the 
translator menu. 

□ If selecting a translator’s menu item causes a dialog box to appear, be sure to 
include three ellipsis points (...) at the end of the menu item’s name. To type the 
ellipsis points, which on the Macintosh are a single character, hold down the 
Option key while you press the semicolon (;) key. 


Designing dialog boxes 

Keep the following suggestions in mind when designing dialog boxes for a translator: 

□ Dialog boxes for translators must be modal; that is, the user must click a button to 
close them before doing anything else. 

□ Dialog boxes should not be too big. If there are too many items for a single dialog 
box, provide one dialog box that includes the most frequently selected options, 
and one or more additional dialog boxes for options that are less frequently 
selected. 

□ When labeling the options in a dialog box, use terms that describe what the user 
sees, not terms that describe the internal details of a file. For example, a button 
labeled “Ignore Left Margin Commands’’ is preferable to one labeled 
“Ignore .LM”. 


Designing About boxes 

An About box is a dialog box that provides information about a particular translator. 

Users can view an About box by choosing the About Apple File Exchange item from 

the Apple menu, selecting the name of a translator in die dialog box that appears, 

then clicking the About button in the dialog box. An About box should contain 

□ the name of the translator and any relevant copyright information 

□ a description of the translator and any options the translator provides 

□ the authorCs) of the translator 

□ the version number of the translator and the date the translator was written 

You can create an About box for a translator in one of two ways: 

□ You can include text for the About box in a resource. Apple File Exchange then 
takes this text and displays it in a dialog box that includes a scroll bar and an OK 
button. This is the simplest approach, but it does not provide any control over the 
font, type size, or type style used for the text. 

□ You can create your own About dialog box for the translator. This approach gives 
you control over the fonts, type sizes, and type styles used for the text, and, in 
addition, allows you to include additional buttons and graphics within the dialog 
box. The About box must be a modal dialog box (that is, one the user must close by 
clicking a button before doing anything else). 


Designing a translator's user interface 
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Translators as resources 

Translators are stored as resources. These resources contain the code and other 
information necessary to perform translations. Apple File Exchange calls a translator 
by loading the translator resource into memory, then jumping to the first instruction 
in the resource. 

Translator resources normally reside in translator files. The only exceptions are 
resources for the translators built into Apple File Exchange, which are part of the 
Apple File Exchange program. Translator files can contain one or more translator 
resources. When opened, Apple File Exchange opens any translator files it finds in the 
Apple File Exchange folder. Other translator files can be kept in other folders and 
moved into the Apple File Exchange folder when needed. 

❖ Note: The Macintosh operating system puts limits on the number of resource files 
an application can have open. For example, Apple File Exchange running on the 
Macintosh Plus can have a maximum of 14 translator files open at the same time. 
This means that if you put several translators together in the same file, users can 
have more translators available in translator menus. If there are fewer translators in 
a translator file, moving the file into or out of the folder containing Apple File 
Exchange affects the availability of fewer translators. 

How do you decide which translators to put in a translator file? In general, you 
should put any translators that are related in the same file. For example, it is a good 
idea to keep a translator and its reverse translator (for example, the translators 
MySpreadsheet to YourSpreadsheet and YourSpreadsheet to MySpreadsheet) 
together in the same translator file. 

The file type of translator files is 'VISA'. The creator for translator files can be either 
'PSPT' or a unique, four-byte creator type. 

❖ Note: If the creator of a translator is 'PSPT, the icon for the translator is provided 
by Apple File Exchange. Assigning the translator a unique creator type allows the 
translator to have its own unique icon. (To ensure that a new creator type is unique, 
you must register the type with Macintosh Technical Support) For information on 
creating an icon for a translator, see the section “Customizing Icons” later in this 
chapter. 
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Resource types for translators 

The resource type for a translator is determined by the source and destination file 
systems for the files it translates. These resource types, which are built out of two-letter 
abbreviations for each file system, are listed in Table 2-1. 


Table 2-1 

Resource types for translators 


Source file 
system 

Destination file 
system 

Translator resource 
type 

Macintosh 

Macintosh 

'MCMC' 

Macintosh 

ProDOS 

'MCPD' 

Macintosh 

MS-DOS 

'PDMS' 

ProDOS 

Macintosh 

'PDMC' 

ProDOS 

ProDOS 

'PDPD' 

ProDOS 

MS-DOS 

'PDMS' 

MS-DOS 

Macintosh 

'MSMC' 

MS-DOS 

ProDOS 

'MSPD' 

MS-DOS 

MS-DOS 

'MSMS' 


For example, a translator that converts MacWrite® files from a Macintosh disk to 
Apple Works® word processing files on an Apple II disk would have the resource type 
'MCPD'. 


Translator resources and menus 

In addition to a resource type, each translator resource has a resource name and a 
resource ID. These resource IDs must be multiples of 25. The resource name is used as 
the translator’s item name in translator menus. The resource ID determines a 
translator’s position in translator menus: 

□ Translators with resource IDs greater than 2000 are special-purpose translators. 
These translators are used in cases where either the source-file format or the 
destination-file format is used by a limited range of applications. Except in very 
rare cases, translators written by suppliers other than Apple will be special-purpose 
translators. Their menu items appear in the top part of translator menus and are 
arranged alphabetically. 

□ Translators with resource IDs less than or equal to 2000 are general-purpose 
translators. These translators convert file formats used by a wide variety of 
applications to other widely used formats. One example is a translator that converts 
text files from one file system to equivalent text files on another file system. Another 
example would be a translator for encrypting files. Except in very rare cases, the 
only general-purpose translators will be those that are built into Apple File 
Exchange. Their menu items appear in the bottom part of menus and are arranged 
in order of their ID numbers, with translators that have higher-numbered IDs closer 
to the top. 

❖ Note: The resource ID 0 is reserved for default translators. Default translators are 
always provided by Apple File Exchange; do not use the resource ID 0 for 
translators you write. 


Translators as resources 
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General-purpose translators have two important limitations that distinguish them 

from special-purpose translators: 

□ They cannot be imported to other menus. 

□ In the dialog box that allows the user to select a translator when more than one 
translator can translate a file, general-purpose translators are not shown. A 
general-purpose translator is not chosen by the user, but is instead used 
automatically when no special-purpose translators can translate a file. It is assumed 
that one or more of the general-purpose translators can translate any file. 

❖ Note: Include a translator among the general-purpose translators only if it is truly 
general-purpose. Never include a translator among the general-purpose 
translators merely to keep it from being imported to another menu. If a translator 
does not accept and create files that can be used by many different applications, it 
should appear with the special-purpose translators. 

Table 2-2 lists resource types, resources IDs, and names for sample resources. 

Figure 2-2 shows the translator menus that result. These menus illustrate how resource 

types, IDs, and names for translators affect translator menus. In the menus, note the 

following: 

□ Translators of resource type 'PDMC' appear in the ProDOS to Mac menu, while 
translators with resource type 'MCPD' appear in the Mac to ProDOS menu. 

□ If ellipsis points (...) are part of the resource name, they appear in the menu. 

Ellipsis points indicate that a dialog box appears when the user selects the menu 
item. 


Table 2-2 

Sample translator resources 


Resource type 

Resource ID 

Resource name 

'PDMC' 

7300 

Applesoft to MS-Basic 

'PDMC' 

2325 

Apple Works to Excel 

'PDMC' 

15000 

VisiCalc to SYLK... 

'PDMC' 

12000 

TXT to MDS 

'PDMC' 

1100 

TXT to TEXT 

'PDMC' 

0 

Default translation 

'MCPD' 

2700 

MacWrite to AppleWorks 

'MCPD' 

3500 

MultiPlan to VisiCalc... 

'MCPD' 

1000 

TEXT to TXT 

'MCPD' 

0 

Default translation 


Figure 2-2 

Translator menus for the translators In Table 2-2 


Mac to ProDos 


✓ MaclUrite to Rpplelllorks 
s MultiPlon to UisICalc... 


✓ TEHTtoTHT 
♦ Default translation 

BtHer Translations... 


ProDos to Mac 


✓ Applesoft to MS-Basic 
^RppleUlorks to Excel 
o'UlsiCalc to SYLK... 

✓ THT to MDS 


✓ TUT to TEHT 
♦ Default translation 

attiar Translations „ 
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Declaring translators 

Translators are functions that are called by Apple File Exchange. To declare a 
translator function, use a declaration of the form 

FUNCTION Translate (Message : integer; 

VAR TranslateData : longint; 

Param : logint; Self : 
handle) : longint; 

The name you choose for a translator function is up to you. The translator parameters 
are described in the following sections. 


Translator parameters 

The following sections describe the parameters to translator functions. 


The Message parameter 

The Message parameter identifies the operation to be performed by the translator. 
Table 2-3 lists the possible values for Message together with constant identifiers and 
meanings for each value. 

Table 2-3 

Values for the Message parameter 

Message 

Constant Identifier value Meaning 


trn_About 

12 

trn_Activate 

4 

trn_Appear 

9 

trn_Deactivate 

5 

trn_Disappear 

10 

trn_Finis 

1 

trn_File 

7 

trn_Get 

2 

trn_GetSettings 

13 

trn_Init 

0 

trn_Load 

11 

trn_NewName 

6 

trn_Recognize 

8 

trn_Set 

3 

trn_SetSettings 

14 


Provide information about the translator 

Activate (check) the menu item for the translator 

Activate translator when the translator’s menu item appears in a 
menu and change apearance of menu item if necessary 

Deactivate (uncheck) the menu item for the translator 

Perform any actions needed (such as freeing memory) when a menu 
containing the translator’s menu item disappears 

Perform any cleanup needed before exiting 

Translate the file 

Return current status of translator 

Get the settings for the translator 

Initialize translator 

Load resources used by the translator 

Return a new name for a file 

Determine if translator can translate a file 

Set status of translator 

Set the settings for the translator 


Complete information about each message is included in Chapter 3, “Messages From 
Apple File Exchange to Translators.” 


Declaring translators 


2-n 



The TranslateDaia parameter 

The TranslateData parameter is used for a translator’s global data. It can be used to 
store 

□ a 32-bit long word that contains the status flags for the translator 

□ a handle to global data for a translator that requires more than four bytes of global 
data 

Storing the translator’s status is the most common use for TranslateData. The status 
flags are shown in Figure 2-3. 


r 


Unused 


"\ 


32 16 

I I I I I I I I.I 


115 


14 


J_L 


11 


Reserved 
Translator bits 
Reserved: Must be 0 


J u 


About_1 

Shadow _ 

Outline — 
Underline — 
Italic — 
Bold — 
Reserved: Must be 0 — 
Reserved: Must be 0 — 
Gray — 
Active_ 

Figure 2-3 
Translator status 


Table 2-4 lists the uses of each of the status flags. 

Table 2-4 

Translator status flags 

Name Bit number Use 


Active 0 


Gray 1 

(Reserved) 2-3 

Bold 4 

Italic 5 

Underline 6 


Set this flag if the translator is active. (The menu 
items for active translators are checked or, in the 
case of default translators, marked with a diamond. 
A translator should normally be active when users 
start up Apple File Exchange.)*! 

Set this flag if the translator is disabled. (Menu items 
for disabled translators are shown in gray.)! 

Reserved for future use. Set these bits to 0. 

Set this flag if the menu item for the translator is to 
appear in bold characters. 

Set this flag if the menu item for the translator is to 
appear in italic characters. 

Set this flag if the menu item for the translator is to 
appear in underlined characters. 
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Table 2-4 (continued) 

Translator status flags 

Name 

Bit number 

Use 

Outline 

7 

Set this flag if the menu item for the translator is to 
appear in outlined characters. 

Shadow 

8 

Set this flag if the menu item for the translator is to 
appear in shadowed characters. 

About 

9 

Set this flag if information about the translator is 
available for display in an About box. 

(Reserved) 

10-11 

Reserved for future use. Set these bits to 0. 

(Translator bits) 

12-14 

Bits reserved for use by the translator. These bits will 
never be used by Apple File Exchange. 

(Reserved) 

15 

Reserved for Apple File Exchange. 

(Unused) 

16-31 

These bits may be used by future versions of Apple 
File Exchange. Use these bits only if necessary; to 
ensure complete compatibility with future versions 
of Apple File Exchange, set these bits to 0. 


•When the trn_Set message is sent to a default translator, Apple File Exchange sets the 
Active flag for the translator. 

fWhen a translator returns an error in response to a tm_Appear message, Apple File Exchange 
clears the translator's Active flag. 

$When a translator returns an error in response to a tm_Appear message, Apple File Exchange 
sets the translator’s Gray flag. 

Figure 2-4 gives Pascal constant definitions for the status flags. 

CONST 


trnActive 


$0001 

trnGray 

= 

$0002 

trnBold 

= 

$0010 

trnltalic 

= 

$0020 

trntJnderline 

= 

$0040 

trnOutline 

= 

$0080 

trnShadow 

= 

$0100 

trnAbout 

= 

$0200 


Figure 2-4 

Pascal constant definitions for status flags 

The Param parameter 

The value of the Message parameter sent to a translator determines how the Param 
parameter is used: 

□ It can be ignored. 

a It can be used for long-word values such as the translator status. 

□ It can be used as a pointer to the translation parameter block. The contents of 
the translation parameter block are described later in this chapter. 

The way in which Param is used with each message is described in Chapter 3, 
“Messages From Apple File Exchange to Translators.” 
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The Self parameter 

The Self parameter is a handle to the memory location where the translator resides. 
This permits the translator to lock itself down (through a call to the Memory Manager 
HLock routine with Self as a parameter) and thus prevents the translator from being 
moved or purged. The parameter can also be used in the following ways: 

□ It allows the translator to change its memory attributes (such as whether it is locked 
or purgable) when exiting. 

a It makes it possible for the translator to get resource information about itself. The 
translator can then use this information when obtaining other resources. 


Results returned by translators 

Translators return results only in response to certain messages from Apple File 
Exchange. The descriptions in Chapter 3, “Messages From Apple File Exchange to 
Translators,” indicate when a message requires a particular result. When no result is 
required, a translator must return 0. 


The translation parameter block 

With certain messages, Apple File Exchange provides a pointer to a translation 
parameter block. The exact contents of the parameter block depend on the operation 
to be performed. The block can contain a variety of information, including 

□ the source and destination file systems for a translation 

□ source and destination directories 

□ names of files to be translated 

□ pointers to procedures that can be called by the translator 

The descriptions in Chapter 3, “Messages From Apple File Exchange to Translators,” 
indicate when a parameter block is sent with a message and describes the contents of 
the block. 
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Type declaration for the translation parameter block 

Figure 2-5 shows a Pascal type declaration for the translation parameter block. 

TYPE TranslateRec = RECORD 


trnLogProc 

: procPtr; 

{Pointer to the Log procedure} 

trnStatProc 

: procPtr; 

{Pointer to the Status 
procedure} 

trnFrID 

: integer; 

{Resource ID of the source 
file system} 

trnToID 

: integer; 

{Resource ID of the 
destination file system} 

trnFrData 

: Ptr; 

{Pointer to global data for 
the source file system} 

trnToData 

: Ptr; 

{Pointer to global data for 
the destination file system} 

trnResrv 

: integer; 

{Used by Apple File 

Exchange} 

trnFrVRef 

: integer; 

{Volume reference for 
source file} 

trnToVRef 

: integer; 

{Volume reference for 
destination file} 

trnFrPar 

; longint; 

{Parent ID for source file} 

trnToPar 

: longint; 

{Parent ID for destination 
file} 

trnNames 

; nameHdl; 

{Handle to names of source 
and destination files) 

trnTested 

: Boolean; 

{TRUE if the translator has 
already tried to recognize 
a file) 

trnAccepted 

: Boolean; 

{If trnTested is also TRUE, 
TRUE indicates that the 
file was recognized} 

trnCountry 

: integer 

{The country code for the 


Macintosh on which Apple 
File Exchange is running } 


END; 

TrnPtr = "'TranslateRec; 

Figure 2-5 

Type declaration for the translation parameter block 
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Contents of the translation parameter block 

This section describes each of the fields in a translation parameter block. 

tmAccepted: If the tmTested field is TRUE, this field indicates whether a file was 
accepted for translation. 

trnCountry: This field contains the country code for the Macintosh system software 
under which Apple File Exchange is running. When transliterating files, translators use 
the country code to identify the source and destination character sets. Current country 
codes and their meanings are listed in the International Utilities Package chapter in 
Volume I of Inside Macintosh. 

trnFrData: This field contains a pointer to global data for the source file system. 

fmFrID: This field contains the resource ID for the source file system. 

IrnFrPar: This field contains the ID for the source directory. 

trnFrVRef: This field contains the volume reference number for the source volume. 

trnLogProc: This field contains a pointer to the User Log procedures CallLog and 
CallErrLog. Translators call these procedures to inform the user of errors and other 
events. For a complete description of these procedures, see the section “Calls From 
Translators to Apple File Exchange” in this chapter. 

tmNames: This field contains a handle to the names of the source and destination 
files. The names are stored in a NameRec record. Figure 2-6 shows a Pascal type 
definition for the NameRec record. 

CONST maxdestnames = 1; 

TYPE NameRec =» RECORD 

nameCnt : integer; {Number of destination files} 

name : array[0..maxdestnames] of str255 

(Names of source and destination files: name[0] contains the name 
of the source file, while name[l] contains the name of the 
destination file. Future releases of Apple File Exchange may 
support multiple destination files.} 

END; 

NamePtr = ''NameRec; 

NameHdl = ^NamePtr; 

Figure 2-6 

The NameRec record 

trnResrv: This field is reserved for use by Apple File Exchange. 

trnStatProc: This field contains a pointer to the Apple File Exchange status 
procedure. Translators call this procedure to inform the user of a translation’s current 
status. For a complete description of the procedure, see the section “Calls From 
Translators to Apple File Exchange” in this chapter. 
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trnTested: This field indicates whether the translator has already been sent a 
tm_Recognize message for a file. If the value of the field is TRUE, the translator does 
not have to determine again if it can translate the file. 

trnToData: This field contains a pointer to global data for the destination file system. 

trnTolD: This field contains the resource ID for the destination file system. 

tmToPar: This field contains the ID for the destination directory. 

trnToVRef: This field contains the volume reference number for the destination 
volume. 


Headers for translators 


All translators must have assembly-language headers of the type shown in 

Table 2-5. 

Table 2-5 

Format for translator headers 

Offset 

Length 

In bytes 

Contents 

Description 

0 

4 

Either 

BRA start 

or 

BRA.S start 
followed by $00 

Assembly-language instruction to 
branch around header* 

4 

4 

$7472616E 

Signature (ASCII 'tran'), which 
indicates that this is a translator with a 
headerf 

8 

2 

ID number 

Same as Resource ID number 

10 

2 

Version number 

Can be used to keep a version number 
for the translator 

12 

n* 

Version 

A Pascal-type string^ for keeping a 
version identifier for the translator 
(for example, “VI.0B”) 

12+ n 

4 

$0000FFFF 

Reserved 

16 + n 

4 

$00000000 

Reserved 

20 + n 

m 

Tables, constants 

Static variables used by the translator 

20 + n + m 


start label 

Label for beginning of translator 


’If a header begins with the BRA.S instruction, the total length of the header cannot exceed 
128 bytes. 

translators written for earlier, prerelease versions of Apple File Exchange did not have 
headers. 

tThe total number of bytes in this field (including the length byte) must be even. 
§Pascal-type strings have the length of the string as the first byte. (For example, the first 
byte of the string “VI.OB” would contain the number 5.) 
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Calls from translators to Apple File Exchange 

Apple File Exchange provides three routines that can be called by translators. 
Translators use these routines to 

□ inform users about the status of a translation 

□ send error messages and other messages to users 
Table 2-6 lists the routines and their uses. 

Table 2-6 

Calls to Apple Hie Exchange 
Routine Description 


CallErrLog Enters a message in the User Log and displays an alert box telling the 
user that there is an addition to the User Log 

CallLog Enters a message in the User Log 

CallStat Provides information about the status of a translation 

Because translators are stored as resources that are separate from Apple File 
Exchange, they cannot call Apple File Exchange routines through normal Pascal 
calling conventions. When making calls from translators written in Pascal to these 
routines, translators must circumvent the normal flow of control through the use of 
inline machine instructions. The MPW Pascal INLINE directive (or the equivalent 
technique in other languages) allows translators to replace the JSR assembly-language 
instruction that concludes normal MPW Pascal routines with other instructions, 
making these calls possible. 

The machine-language instructions used for each call to an Apple File Exchange 
routine are described with the routine. For information on Pascal calling conventions, 
see Appendix A, “Pascal Conventions for Translators.” For information on the 
INLINE directive, see the Macintosh Programmer's Workshop Pascal Reference. 


Logging errors 

A translator must put an error message in the User Log whenever it fails to translate a 
file. It should also log other problems that it encounters if the information may be 
useful to users. It is important to include an explanation of why the error occurred. 
Some errors result from problems outside the control of the translator, such as 
input/output errors, while Other errors are the result of problems within the translator. 

Apple File Exchange provides two different procedures for logging messages: 
CallErrLog and CallLog. After all translations are complete, CallErrLog displays a 
dialog box informing the user that an error has occurred. CallLog does not display a 
dialog box. 
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When you design a translator, pay special attention to the text of error messages: 

□ Be specific. Let users know exactly what caused the problem. 

□ Use terms all users will understand. Avoid terms that are specific to a particular 
application or file system. 

□ Be complete. Use as many characters as you need to produce descriptive, helpful 
messages. 

❖ Note: When translating more than one file, Apple File Exchange does not stop 
when an error occurs. Because of this, it is essential that translators record errors in 
the User Log. 


Including other information in the User Log 

Translators can use the User Log to communicate other information that’s of interest 
to users. For example, translators can note when any characteristics of a document, 
such as the format or fonts used, are changed during translation. Once again, 
consider the needs of your audience: if something happens that affects what users can 
do with a translated file, put a message in the User Log. 


Indenting messages 

When Apple File Exchange translates nested files and folders, the User Log can show 
the nesting by indenting entries. Figure 2-7 shows an example of indentation within the 
User Log. 


Copying Mac to Mac, 7/29/87, 10:59:24 AM 


APS 2.0 — 
1-Column 

1- Column 

2- Column 
2-Column 


APS 2.0 (Folder 


Glossary 2.0 
Template 2.0 
Glossary 2.0 
Template 2.0 


—> 1-Column 
—> 1-Column 
—> 2-Column 
—> 2-Column 


Glossary 

Template 

Glossary 

Template 


2.0 

2.0 

2.0 

2.0 


{Default 

{Default 

{Default 

{Default 


translation} 

translation} 

translation} 

translation} 


Figure 2-7 

Indentation within the User Log 


Translators can control whether indentation occurs. Entries associated with a 
particular file should normally be indented; indenting the entries causes them to 
appear immediately above or below the User Log entry for the file. There are, 
however, cases where you may want to turn off the indentation for an entry. For 
example, suppose a translator for a word-processing document informs the user that a 
footnote cannot be translated, then lists the text of the footnote in the User Log. By 
turning off indentation for the footnote listing, the translator can make it easier for the 
user to copy the footnote from the User Log and paste it into the newly translated 
document. 
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CallErrLog—adds an error message to the User Log 


Description 


When called 


Declaration 


The CallErrLog procedure allows a translator to put error messages and other 
information in the User Log. Unlike CallLog, calling CallErrLog causes an alert box to 
be displayed after all translations are finished. The alert box contains the message 
“An error occurred during the translation. Please check the User Log for more 
information.” 


The CallErrLog procedure must be called whenever an error occurs during a 
translation. 


Procedure CallErrLog (Str : str255; CR : Boolean; Indent ; Boolean; 
LogProc : procptr); 

INLINE $205F, $1F5F, $0001, $002F, $0080, $0001, $4E90; 

The inline instructions are hexadecimal equivalents for these 68000 assembly 
language instructions: 

; Pop the address of the log procedure off the stack 

; and put it A0 

MOVE.L (A7)+, A0 

; Pop the Indent parameter off the stack and put it in the 
; byte after the CR parameter on the stack 
MOVE.B (A7)+, 1(A7) 

; Change the flag that indicates that this is a CallErrLog 
; call rather than a CallLog call. (The address of these 
; two calls is the same.) 

ORI.B #$80, 1(SP) 

; Use the JSR instruction to push a return address 
; on the stack and then jump to the log procedure 
; pointed to by A0 
JSR (A0) 
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Input 


Output 

Notes 


Example 

See also 


The input parameters for the CallErrLog procedure are 

Str A Pascal-type string that contains a description of an error or 

information about another event of interest to the loser. (Pascal- 
type strings have as their first byte the number of characters in the 
string; for example, the string “LONG” has 4 as its first byte.) The 
string can contain up to 255 characters. 

CR TRUE if the description in Str is to be followed by a carriage return; 

FALSE if not. 

Indent TRUE if the description in Str is to be indented to reflect the nesting 

of the file or directory being translated; FALSE otherwise. 

LogProc A pointer to the CallErrLog procedure. The translator must get this 

pointer from the tmLogProc field of the translation parameter 
block. 

None. 


The alert box informing the user about an error appears immediately after all 
translations are complete, not during the translations. 

CallErrLog should be used to log errors and other unexpected events. CallLog can be 
used to put any other information in the User Log. 

Although translators may call CallErrLog more than once when translating files, only 
one alert box appears when the translations are finished. 

If the message you want to send is longer than 255 characters, simply call CallErrLog 
or CallLog as many times as necessary to send the entire message. 

CallErrLog (MyString, TRUE, TRCJE, MyData , '.trnLogProc) ; 

puts the message in MyString in the User Log and requests that the message be 
indented as necessary to reflea the nesting of the file being translated. The alert box 
contains the message “An error occurred during the translation. Please check the 
User Log for more information." 

The descriptions of the trn_File message and the CallLog procedure. 


CallErrLog 
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CallLog—adds a message to the User Log 

Description The CallLog procedure allows a translator to put messages and other information in 
the User Log. 

When called The CallLog procedure should be called whenever an event occurs during a 
translation that may be useful for the user to know about. 

Declaration Procedure CallLog (Str : str255; CR : Boolean; Indent : Boolean; 

LogProc ; procptr); 

INLINE S205F, $1F5F, $0001, $4E90; 

The inline instructions are hexadecimal equivalents for these 68000 assembly 
language instructions: 

; Pop the address of the CallLog procedure off the stack 

; and put it A0 

MOVE. L (A7) +, AO 

; Pop the Indent parameter off the. stack and put it in the 
; byte after the CR parameter on the stack 
MOVE. B <A7)+, 1 (A7) 

; Ose the JSR (Jump to Subroutine) instruction to push a 
; return address on the stack and then jump to the CallLog 
; procedure pointed to by A0 
JSR (A0) 

Input The input parameters for the CallLog procedure are 

Str A Pascal-type string that contains the message to be logged. 

(Pascal-type strings have as their first byte the number of characters 
in the string; for example, the string “LONG” has 4 as its first byte.) 
The string can contain up to 255 characters. 

CR TRUE if the description in Str is to be followed by a carriage return; 

FALSE if not. 

Indent TRUE if the description in Str is to be indented to reflect the nesting 

of the file or directory being translated; FALSE otherwise. 

LogProc A pointer to the CallLog procedure. Translators can get this pointer 

from the tmLogProc field of the translation parameter block. 

Output None. 
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Notes 


CallErrLog should be used to log errors and other unexpected events. CallLog can be 
used to put any other information in the User Log. This information can include 
changes to any file components (for example, fonts) that occur during translation, 
and information about a translation specifically requested by the user. 

If the message you want to send is longer than 255 characters, simply call CallLog as 
many times as necessary to send the entire message. 

Example CallLog (MyString, TRUE, TRUE, MyData"' .trnLogProc) ; 

puts the message in MyString in the User Log and follows it by a carriage return. In 
addition, it requests that the message be indented as necessary to reflect the nesting of 
the file being translated. 

See also The descriptions of the tm_File message and the CallErrLog procedure. 
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Reporting the progress of a translation 

While translating a file, a translator must periodically use the Calls tat function to 

inform the loser of the progress it’s making. The user sees this progress as a percent- 

complete value in a thermometer, as shown in Figure 2-8. 

07. 257. 507. 75% 1007. 

Figure 2-8 

Status thermometer 

The accuracy of the reporting will inevitably be different for different translators. As 

you design a translator, keep in mind these points: 

□ The thermometer display should begin at 0 for each file translated. 

□ As a minimum, the thermometer should indicate that the translator is making 
progress during a translation. Any change in the thermometer readings will let the 
user know that the translator is working. 

□ Ideally, the thermometer will indicate how much more time the translation will 
take. For example, if the change from 0 percent to 25 percent took 10 seconds, the 
time it takes to go from 25 percent to 100 percent should be as close to 30 seconds as 
possible. Achieving a reasonable level of accuracy may be difficult, but it is worth 
the effort. 
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CallStat—informs the user of a translator’s progress 


Description 


When called 


Declaration 


Input 


Output 


With the CallStat function, a translator can inform the user about the progress of a 
translation. Translators provide the CallStat function with 

□ a string describing the operation taking place 

□ a percent-complete value for the translation 

Apple File Exchange then displays the string together with a bar graph showing the 
percent-complete value. 


The CallStat function must be called periodically during the actual translation of a file 
(that is, after the translator receives the tm_File message from Apple File Exchange 
and accepts the file to be translated). 


Function CallStat (StatMsg : str255; StatPct : integer; DestFNum : integer; 
StatProc : procptr) : Boolean; 

INLINE S205F, $4E90; 

The inline instructions are hexadecimal equivalents for these 68000 assembly 
language instructions: 

; Pop the address of the CallStatus function off the stack 

; and put it AO 

MOVE.L (A7)+, AO 

; Use the JSR (Jump to Subroutine) instruction to push a 
; return address on the stack and then jump to the CallStatus 
; function pointed to by AO 
JSR (AO) 


The input parameters for the CallStat function are 

StatMsg A Pascal-type string that is displayed by Apple File Exchange during 

the translation. (Pascal-type strings have as their first byte the 
number of characters in the string; for example, the string “LONG” 
has 4 as its first byte.) 

StatPct An integer between 0 and 100 that indicates the progress of the 

translation. 


DestFNum Contains the value 1. 


StatProc A pointer to the CallStatus function. The translator must get this 

pointer from the trnStatProc field of the translation parameter 
block. 


The CallStat function returns the function result FALSE if the user has clicked the 
Cancel button. The function result TRUE indicates that the translator can continue. 


CallStat 
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Notes 


Example 


See also 


The value for StatPct should reflect the progress of the entire translation process. 
Even if there are several discrete tasks involved in a translation, StatPct should reflect 
the total progress toward translating the file. For more information, see the previous 
section “Reporting the Progress of a Translation.” 

If the StatMsg parameter is empty (that is, it is a string whose length is 0), Apple File 
Exchange displays the most recently displayed message. To erase the last message 
displayed, include a space character as the StatMsg parameter. 


Result := CallStat (MyString, 33, 1, MyData''.trnStatProc) ; 

displays MyString and shows that the translation is one-third finished. 


The description of the trn_File message. 
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Calls from translators to file systems 

To perform operations involving files, translators call file system routines. For both 
the Macintosh Hierarchical File System (HFS) and other file systems (known as 
foreign file systems), translators use the CallFS function described below. 

❖ Note: While it is possible for translators to call HFS and other file system routines 
directly, translators should instead use the CallFS function. Apple File Exchange 
relies on the CallFS interface to properly handle certain events, such as the 
swapping of disks. 


File systems as resources 

The CallFS function provides a single, uniform interface to file systems. It does this by 
providing access to file system resources. Apple File Exchange provides a file 
system resource for each of the file systems it supports. Calls to the Macintosh file 
system resource are identical to the HFS calls described in “The File Manager” chapter 
in Volume IV of Inside Macintosh. Chapters 4 and 5 describe the calls available for 
the ProDOS and MS-DOS file systems. 

File system resources for file systems other than the Macintosh—those for ProDOS 
and MS-DOS—are called foreign file systems. The calls for these file systems are 
modeled on the corresponding Macintosh HFS calls. Many calls are identical for all 
file systems. For example, you can use the same FFClose call to close Macintosh, 
ProDOS, and MS-DOS files. There are, however, differences between many calls that 
reflect differences in the file systems. These differences are described in Chapters 4 
and 5. 

File systems are kept in resources whose type is '4NFS'. Because these resources are 
separate from translator resources, translators cannot make calls to file systems 
resources through normal Pascal calling conventions. As with Apple File Exchange 
routines, translators written in Pascal must circumvent the normal flow of control 
through the use of inline machine instructions. The MPW Pascal INLINE directive (or 
the equivalent technique in other languages) allows translators to replace the JSR 
assembly-language instruction that concludes normal MPW Pascal routines with other 
instructions, making these calls possible. 

The machine-language instructions used for the CallFS function are described with the 
function. For information on Pascal calling conventions, see Appendix A, “Pascal 
Conventions for Translators.” For information on the INLINE directive, see the 
Macintosh Programmer’s Workshop Pascal Reference. 
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Using the translation parameter block for file system calls 

A file system resource can be both relocated and purged, so calling it requires getting a 
handle to its current location in memory. For any translation, the translation 
parameter block contains the resource IDs for both the source and destination file 
systems; the IDs can then be used in GetResource calls to get the handles. In addition, 
file systems have global storage that they use in much the same way as translators. A 
call to a file system must include a pointer to this global storage, which is kept in the 
translator parameter block. 

The translation parameter block also includes volume reference numbers, parent ID 
numbers, and filenames for both the source and destination files. With this 
information, translators can make any of the file system calls. 
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CallFS—oalls a file system routine 


Description 
When called 

Declaration 


Input 


Output 


The CallFS function allows a translator to perform operations involving a file system. 


The CallFS function is called whenever a translator needs to perform a file system 
operation, including such operations as creating, renaming, reading, and writing 
files. The description of the Msg parameter in Table 2-7 lists all of the possible 
operations. 


Function CallFS (Msg :■ integer; FSData : ptr; PB : ptr; 

Async : Boolean; FSRoutine : handle) : OSErr; 

INLINE $2057, $2050, $4E90; 

The inline instructions are hexadecimal equivalents for these 68000 assembly 
language instructions: 

; Get the handle to the file system from the stack 
; and put it in register A0 
MOVE.L (A7), A0 

; Dereference the handle to get the pointer to the file 
; system; put the pointer in register A0 
MOVE.L (A0), A0 

; Ose the JSR (Jump to Subroutine) instruction to push a 
; return address on the stack and then jump to the file 
; system pointed to by A0 
JSR (A0) 


The input parameters for the CallFS function are 


Msg 

FSData 

PB 


Async 


FSRoutine 


Identifies the desired operation. Table 2-7 lists file system 
operations and their corresponding Msg values. 

A pointer to the global data for this file system. 

Usually a pointer to a parameter block used for the call. See 
Chapters 4 and 5 for the parameter block pointed to for each call. 

TRUE if the operation is to be performed asynchronously. This 
parameter applies only to operations that support asynchronous 
operation. 

Note: The ProDOS and MS-DOS file systems do not support 
asynchronous operation. 

A handle to the resource containing the file system. 


The CallFS function returns an Operating System result code as the function result. If 
the result is noErr (= 0), the operation was completed successfully. 


CallFS 
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Notes To ensure proper operation of Apple File Exchange, translators should use CallFS for 

Macintosh file system calls rather than make direct calls to the Macintosh File 
Manager. 


Example ResultCode := CallFS (FFGetVInfo, MSDOSData, 

PBHParamBlockRecPtr, FALSE, MSDOSHandle); 

calls the FFGetVInfo routine to get information about a volume. The parameter block 
is used to pass information about the volume to the routine and back to the calling 
translator. The operation is performed synchronously. 


See also Chapters 4 and 5 for details about each value of the Msg parameter. 


Table 2-7 

Values for the CallFS Msg parameter 


Constant identifier Value Constant identifier Value 


FFAllocate 

19 

FFOKFName 

52 

FFAllocContig 

20 

FFOpen 

9 

FFClose 

22 

FFOpenRF 

10 

FFCloseWD 

36 

FFOpen WD 

35 

FFCreate 

23 

FFRead 

13 

FFDelete 

25 

FFRename 

31 

FFDirCreate 

24 

FFRstFLock 

29 

FFFlushFile 

21 

FFSetCatlnfo 

33 

FFFlushVol 

5 

FFSetEOF 

18 

FFGetCatlnfo 

32 

FFSetFInfo 

27 

FFGetEOF 

17 

FFSetFLock 

28 

FFGetFInfo 

26 

. FFSetFPos 

16 

FFGetFPos 

15 

FFSetFVers 

30 

FFGetVInfo 

1 

FFSetVInfo 

2 

FFGetWDInfo 

37 

FFUnlockRange 

12 

FFLockRange 

11 

FFWrite 

14 

FFMakeDName 

54 

FFXGetCatlnfo 

50 

FFMakeFName 

47 

FFXSetCatlnfo 

51 

FFOKDName 

53 
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Calls from translators to transliteration routines 

Translators can move files between different computers used in the same country. To 
do this, translators that translate text must be able to transliterate files, that is, to 
convert the characters in a file to equivalent characters in another character set. Here 
is an example: a translator is moving a file containing text from a French Apple II to a 
French Macintosh. One of the characters to be translated is the character a. This 
character is represented by the hexadecimal number 40 on the French Apple n, while 
on the Macintosh the same character is represented by the hexadecimal number 88. 
The translator must see to it that the French Apple II representation for the d —and for 
all the other characters in the file—is converted to the representation used by the 
Macintosh. 


About transliteration procedures and TProcs 

A transliteration procedure is any procedure that a translator uses to transliterate 
files. With Apple File Exchange and certain other applications, Apple provides 
transliteration resources known as TProcs. If a TProc for a particular transliteration is 
not available, translators must provide their own transliteration procedure. 

When designing a translator, observe the following rules: 

□ If your translator translates text, use TProcs whenever appropriate. Your translator 
should be able to transliterate between any of the character sets for which there are 
TProcs. 

□ Be aware that certain applications (for example, Lotus 1-2-3) use their own 
character sets. If you are designing a translator for files created by such an 
application, you must provide your own transliteration routines. 

□ Keep all text strings displayed by translators in resources. The resource IDs for 
these strings should be in the same range as the resource ID for the 

translator—specifically, the range [translator-resource-ID..translator-resource-ID 
+ 24], 

When a translator moves a file containing text to a computer, file system, or 
application with a different character set, it must transliterate the file. Transliterating a 
file converts the representation of each character in a file to the representation used in 
another character set. Apple File Exchange provides TProcs that perform 
transliterations between character sets used by computers in the same country. For 
example, on a French Macintosh there are TProcs available for transliterating text 
between a French Apple n, a French Macintosh, and a French IBM PC. Each TProc 
handles two transliterations: the transliteration from one character set to a second 
character set and the transliteration from the second character set to the first. The 
following sections explain how to use TProcs. 

When there is no TProc for a particular transliteration, such as a transliteration 
involving a special character set used by an application, translators must provide their 
own transliteration routines. 
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TProcs as resources 

TProcs are kept in resources whose resource type is 'tprc'. In turn, TProcs are grouped 
into resources known as TProc families. TProc families contain all the available 
TProcs for transliterating files within the same source country. For example, all 
TProcs for transliterating files that originated on a French version of the Macintosh, 
Apple n, or IBM PC are in one TProc family, while TProcs for files that originated on 
an Italian version of the Macintosh, Apple II, or IBM PC are in another. 

One TProc family is built into Apple File Exchange. Both the source country and 
destination country for this TProc family are the same as the country code for the 
version of the Macintosh system software with which it is included. (Country codes are 
described in the “International Utilities Package” chapter in Volume I of Inside 
Macintosh .) This means that there are TProcs for transliterating files between versions 
of the Macintosh, Apple n, and IBM PC that are designed for the same country. 

TProcs for transliterating between languages used in different countries may be 
provided with other applications, such as terminal emulators, but they are not 
included with Apple File Exchange. 

The resource type of TProc families is 'tprf. 

The source and destination countries for TProcs provided with Apple File Exchange 
are always the same. 

The resource ID for a TProc family is the same as the country code for the Macintosh 
with which Apple File Exchange is bundled. Country codes are listed in the 
“International Utilities Package” chapter in Volume I of Inside Macintosh. When 
necessary, additional country codes will be defined by Macintosh Technical Support. 

Because TProc resources are separate from translator resources, translators cannot 
make calls to TProcs through normal Pascal calling conventions. As with Apple File 
Exchange routines, translators written in Pascal must circumvent the normal flow of 
control through the use of inline machine instructions. The MPW Pascal INLINE 
directive (or the equivalent technique in other languages) allows translators to replace 
the JSR assembly-language instruction that concludes normal MPW Pascal routines 
with other instructions, making these calls possible. 

The machine-language instructions used for TProcs are described with the sample 
TProc that follows. For information on Pascal calling conventions, see Appendix A, 
“Pascal Conventions for Translators.” For information on the INLINE directive, see 
the Macintosh Programmer’s Workshop Pascal Reference. 
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Structure of TProc family resources 

A TProc family contains a record of the form 

TPRF = RECORD 

LastEntry : integer; 

Reserved : array[1..31] of integer; 

TProcs : array(1..LastEntry] of TPRCEntry 

END; 

The fields in the TPRF record have the following meanings: 

LastEntry The number of TProcs in the family. 

Reserved Reserved for future expansion; may contain version information in 

the future. 

TProcs An array with LastEntry elements containing information about each 

TProc in the family. The form of the entries is described below: 

CharFam : integer; 

CountryCode : integer; 

TPRCEntry = RECORD 

tprcID : integer; 

curCharFam : CharFam; 

altCountry ; CntryCode; 

altCharFam : CharFam 

END; 

The fields in the TPRCEntry record have the following meanings: 

tprcID The resource ID of the TProc. 

curCharFam The character set family number for the TProc’s source character set. 

Character family values for Apple File Exchange TProcs are listed in 
Table 2-8. 

altCountry The country code for the destination country. This code is the same 
as the resource ID for the TProc family. For TProcs provided with 
Apple File Exchange, the source country code and destination 
country code are always the same. 

altCharFam The character set family number for the TProc’s destination character 
set. 
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Table 2-8 

CharFam values for Apple 
File Exchange TProcs 

Name Value 


cfMacintosh 0 

cfASCII 1* 

cflBMPC 2 

"cfASCII is the CharFam value 
for character sets used by the 
Apple II. 


Using TProcs 

These are the steps a translator must perform when using a TProc: 

1. Get the value of the tmCountry field from the translation parameter block. This 
field identifies the international version of the Macintosh on which Apple File 
Exchange is running. The value is the same as the country code for the Macintosh 
on which Apple File Exchange is running. 

2. Using the GetResource routine, open the TProc family resource whose resource ID 
is the same as the country code from step 1. 

3 • Search the table of entries in the family for the TProc with the correct curCharFam 
and altCharFam values. For example, to find the TProc for transliterating a file 
from an Apple II to a Macintosh, search for the entry where one of the two fields 
curCharFam or altCharFam contains 1 and the other field contains 0. 

4. The tprcID field for the entry contains the TProc’s resource ID. Use the value from 
this field to open the TProc resource. 

5. Call the TProc. 


2-34 


Chapter 2: Writing Translators 





Translit—an example of a TProc 


Description 
When called 

Declaration 


A TProc transliterates the characters in a file. 

A TProc is called when the character set families for the source and destination files 
are different. 


TYPE 

CharFam = integer; (Code for character set family) 

CntryCode = integer; (Country code for TProc source or destination 

country) 

TransText = RECORD 


trPtr 


ptr; 

trLen 


longint; 

trFont 


integer 

END; 



TransPB = RECORD 



verb 


integer; 

featureFlags 


integer; 

result 


OSErr; 

newCntry 


integer; 

srcText 


TransText; 

dstText 


TransText; 

tpRsrv 


array [0..3] OF longint 


END; 

FUNCTION Translit (params : TransPB, Self : handle) : OSErr; 
INLINE $2057, $2050, $4E90; 


Translit 
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The inline instructions are hexadecimal equivalents for the following 68000 assembly 
language instructions: 

; Take the handle to the TProc off the stack 
; and put it in register AO 
MOVE. L (A7) , AO 

; Dereference the handle to get the pointer to the TProc; 

; put the pointer in register AO 
MOVE.L (AO), AO 

; Use the JSR (Jump to Subroutine) instruction to push a 
; return address on the stack and then jump to the TProc 
; pointed to by AO 
JSR (AO) 

Input The input parameters for a TProc are 

verb Indicates the operation to be performed by the TProc. It can have 

one of the following values: 

translnit = 0; {Initialize the TProc; performed before 

using TProc) 

transDone =1; {Perform any cleanup required after 

using TProc) 

transLowToHigh =2; {Transliterate from lower-numbered 

character set family to higher- 
numbered character set family) 

transHighToLow =3; {Transliterate from higher-numbered 

character set family to lower- 
numbered character set family) 

featureFlags Apple File Exchange TProcs do not support any of the features 
indicated by these flags. Set this field to 0. 

newCntry For input, set this field to -1. 

srcText.trPtr Pointer to the source buffer for the transliteration. 

srcText.trLen The length, in bytes, of the source buffer. 

srcText.trFont The font number of the font used in the source file. For Macintosh 
files, this is the font number recognized by the Font Manager. For 
Apple II and IBM PC files, this field is set to 0. 

dstText.trPtr Pointer to the destination buffer for the transliteration. 

dstText.trLen The length, in bytes, of the destination buffer. 

dstText.trFont The font number of the font used in the destination file. For 

Macintosh fonts, this is the font number recognized by the Font 
Manager. The meaning of the number for other computers varies, 
but 0 typically refers to the system font, while 1 refers to the font 
used by most applications. (For some computers, dstTexLtrFont 
may be the same as the system font) 

tpRsrv For input, the elements of this array must be set to 0. 

Self Handle to the TProc function. 
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Output 


Example 


See also 


TProcs return an Operating System result code as the function result. If the result is 
noErr (= 0), the transliteration was performed successfully. In addition to the 
standard Macintosh result codes, the following result codes are defined for TProcs: 


tDstTooShort = -501; 
tSubsetSwitch = -502; 
tPartialChar = -503; 


{Destination buffer too short} 

{Source changed character subset) 
{Source ends with a partial character} 


The following parameters are also used for output: 


result 

newCntry 

srcText.trPtr 

srcText.trLen 

dstText.trPtr 

dstText.trLen 


Copy of the function result 

Country code for the TProc used 

Pointer to the source buffer for the transliteration 

Number of bytes from the source buffer that were not translated 

Pointer to the destination buffer for the transliteration 

Number of bytes in the destination buffer that were not used 


ResultCode := Translit (MyParamBlock, MySelf); 

transliterates the buffer pointed to by MyParamBlock.srcText.trPtr and puts the result 
in the buffer pointed to by MyParamBlock.dstText.trPtr. ResultCode contains the 
result code for the function. 


The translator example in Appendix C. 


Translit 
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Advanced topics 

The following sections present advanced topics related to translator implementation. 


Customizing icons 

You can create your own icon for a translator file by following these steps. 

1. Create the translator file. The file type for this file is 'VISA'. 

2. Assign the file a unique four-byte creator type. The Finder™ will use this creator 
type to identify the icon that goes with the file. 

3 • Register the creator type with Macintosh Technical Support. 

4. In the resource file containing the translator, include a version data resource whose 
resource type is the same as the creator type for the translator and whose resource 
ID is 0. 

5. Using ResEdit, create a bundle ('BNDL') and put it in the resource file containing the 
translator. The owner name for the resource must be the same as the creator type 
for the translator and the owner ID must be 0. 

6. Create an icon resource C'ICN#') in the resource file containing the translator. This 
icon is what will be displayed in the Finder. The icon should be the same as the 
icons used for translators provided by Apple, with one exception: you must replace 
the Apple logo in the lower-right comer of the icon with a logo of your own design. 

7. In the resource file containing the translator, include file reference resources that 
link the icon and the file type 'VISA'. 

8. Set the bundle bit for the translator. 

For more information about icons, see the “Finder Interface” chapter in Volume IE of 

Inside Macintosh. 


Translating files in place 

Apple File Exchange allows the source file for a translation to be the same as the 
destination file. When performing such a translation, translators must create a 
temporary file for the results of the translation, then replace the original file with the 
translated version. 
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Examples of translations 

The following examples illustrate the tasks translators perform. They show the 
relationships between 

□ actions by Apple File Exchange users 

□ messages sent by Apple File Exchange to a translator 

□ what the translator does when it’s sent a message 

For detailed information about each of the messages and about messages not included 
in the examples, see Chapter 3, “Messages From Apple File Exchange to Translators.” 
For information on using Apple File Exchange, see the Apple File Exchange chapters 
in the Macintosh Utilities User's Guide. For the Pascal code for a sample translator, see 
Appendix C, “An Example of a Translator.” 


A simple translation 

This example shows what occurs during a simple session with Apple File Exchange. 


What the user does 

Message sent 

What the translator does 

Starts Apple File 
Exchange 

trn_Init 

Initializes any global variables it needs 


trn_Get 

Provides its current status (Apple File 
Exchange uses this status to determine if an 
About button should be available for the 
translator) 

Inserts disk 

trn_Appear 

Learns that the menu containing its menu 
item is active; may allocate more global 
memory or change the appearance of its 
menu item 


trn_Get 

Provides its current status (Apple File 
Exchange gets this information before 
displaying the translator’s menu item) 

Selects file 
to translate 

No message 
sent 


Presses Translate 
button 

trn_NewName 

Provides a new name for the file to be 
translated 


trn_File 

Translates the file 

Exits Apple File 
Exchange 

trn_Finis 

Releases any global memory it has allocated 
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A canceled translation 


In this example, no file is actually translated. The example demonstrates some of the 


features that give Apple File Exchange its flexibility. 

What the user does 

Message sent 

What the translator does 

Starts Apple File 
Exchange 

trn_Init 

Initializes any global variables it needs 


trn_Get 

Provides its current status (Apple File 
Exchange uses this status to determine if an 
About button should be available for the 
translator) 

Inserts disk 

trn_Appear 

Learns that the menu containing it is active; 
may allocate more global memory or change 
the appearance of its menu item 


trn_Get 

Provides its current status (Apple File 
Exchange gets this information before 
displaying the translator’s menu item) 

Selects Eligible 

File command 

trn_Recognize 

Determines if it can translate the file (a 
tm_Recognize message is sent for each file 
in the current directory) 

Deselects 
a translator 

trn_Deactivate 

This message is sent only to the translator 
that was deselected; if this is the translator, 
then it updates its status 


trn_Recognize 

If its menu item appears below the menu item 
for the translator that was deselected, it 
determines again if it can translate a file 

Selects files 

No message 
sent 


Deselects Eligible 
File command 

No message 
sent 


Selects Rename 

Dest. Files 
command 

trn_NewName 

Provides a new name for a file to be 
translated 

Renames 
destination files, 
clicks Cancel box 

No message 
sent 


Ejects disk 
containing 
the Apple File 
Exchange 

trn_Load 

Loads any resources from disk that it needs 
(this makes it less likely that the user will 
have to reinsert the disk) 

Selects 

About AFE 
command 

trn_About 

Provides a dialog box that describes the 
translator or returns the ID of a text resource 
containing a description of the translator 
(in the latter case, Apple File Exchange 
opens the text resource and displays it in a 
dialog box) 

Exits Apple File 
Exchange 

trn_Finis 

Releases any global memory it has allocated 
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This chapter provides detailed reference information about the messages sent to 
translators by Apple File Exchange. Table 3-1 lists the messages sent to translators and 
summarizes the actions that translators must perform in response to the messages. 
Following the table are descriptions of each of the messages. 


Table 3-1 

Messages sent to translators 
Message What translator must do 


trn_About 

trn_Activate 

trn_Appear 

trn_Deactivate 

trn_Disappear 

trn_File 

trn_Finis 

trn_Get 

trn_GetSettings 

trn_Init 

trn_Load 

trn_NewName 

trn_Recognize 

trn_Set 

trn_SetSettings 


Provide information about the translator 

Activate (check) the menu item for the translator 

Perform any actions necessary (such as changing the appearance 
of the menu item) when a menu containing the translator appears 

Deactivate (uncheck) the menu item for the translator 

Perform any actions (such as freeing memory) needed when a 
menu containing the translator’s menu item disappears 

Translate a file 

Perform any cleanup needed before exiting 

Return current status of the translator 

Get the current settings for the translator 

Initialize the translator 

Load resources used by the translator 

Return a new name for a file 

Determine if the translator can translate a file 

Set status of the translator 

Set the settings for the translator 
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trn_About—provide information about the translator 


Description 


When sent 


Input 


Output 


Notes 


The trn_About message requests a translator to provide information about itself, 
either by displaying a dialog box or by providing text containing information about 
the translator. 


This message is sent to a translator when the user selects the About Apple File 
Exchange menu item from the Apple menu and then selects the translator in the 
dialog box that appears. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData 

trnFrID 

trnLogProc 

trnToData 

trnToID 


Pointer to global data for the source file system 

Resource ID for the source file system 

Pointer to the User Log procedure 

Pointer to global data for the destination file system 

Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


The translator can return one of three function results: 

□ The value 0 if the translator displays its own dialog box that includes information 
about the translator. 

□ The resource ID for a resource of type 'TEXT. This resource, which contains 
information about the translator, must contain only printable ASCII characters 
and carriage returns. 

□ A negative number (usually an error code) if no About information is available. 


Apple File Exchange displays text from a TEXT resource in a TextEdit window that 
includes a vertical scroll bar and a close box. To enable the text to fit within the 
window, it breaks lines at word boundaries where necessary. 

An About 'TEXT resource consists of a string of printable characters with carriage 
returns to separate paragraphs. The maximum size of an About 'TEXT' resource is 
32K. 


trn_About 
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Description 

When sent 

Input 


Output 

Notes 


See also 

3-4 trn. 


trn_Activate—activate the translator 


The trn_Activate message informs a translator of events involving the menu item for 
the translator (see “When sent” below) and requests an updated translator status. 


The tm_Activate message is sent when a user 

□ selects an inactive translator from a menu 

□ holds down the Option key while selecting an available menu item (that is, a menu 
item that is not gray) 

In the second case, the tm_Activate message is sent whether or not the translator is 
active. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData 

trnFrID 

trnLogProc 

trnToData 

trnToID 


Pointer to global data for the source file system 

Resource ID for the source file system 

Pointer to the User Log procedure 

Pointer to global data for the destination file system 

Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


The translator updates its status flags and returns them as the function result. 


For many translators, the only action required in response to a tm_Activate message 
is to set the Active flag in their status flags and return the new status as the function 
result. Note, however, that translators are not required to set the Active flag in 
response to this message. For example, some translators display a dialog box when 
their menu item is selected. If a user deactivates the translator by clicking the Cancel 
button in the dialog box, the translator would not set the Active flag. 

When it receives the trn_Activate message, a translator can also allocate any global 
memory it needs before being activated. As discussed in the description of the 
tm_Init message, translators that use large amounts of global data can help to 
conserve memory by deferring memory allocation until they receive a trn_Activate, 
tm_Appear, or tm_File message, depending on the memory needs of the 
translator. In doing so, the translators avoid allocating memory before they actually 
use it. 

A tm_Activate message is sent whenever a default translator is chosen, but no 
tm_Deactivate message is ever sent for a default translator. 


trn_Deactivate and trn_Init. 


Activate 




trn_Appear—respond to menu appearance 


Descripfion 

When sent 

Input 

Output 

Notes 


The trn_Appear message informs a translator that a menu containing its menu item 
will appear in the menu bar. The translator can then determine the file systems for the 
new menu and perform any actions, such as changing the appearance of its menu 
item or allocating more memory, that are necessary. 


The trn_Appear message is sent when 

□ the user selects a new source or destination disk in either of Apple File Exchange’s 
file windows 

□ a translator is imported to a new menu 


Apple File Exchange passes a pointer to the translation parameter block in the Param 
parameter. For this message, the translation parameter block includes these values: 


trnFrData 

trnFrID 

trnFrVRef 

trnLogProc 

trnToData 

trnToID 

trnToVRef 


Pointer to global data for the source file system 

Resource ID for the source file system 

Volume reference for the source disk 

Pointer to the User Log procedure 

Pointer to global data for the destination file system 

Resource ID for the destination file system 

Volume reference for the destination disk 


All other values in the translation parameter block for this message are undefined. 


The translator returns the function result 0 if the operation was successful or an error 
code (usually for a memory allocation or file system error) if it was not. 


Upon receiving the trn_Appear message, a translator can get information about the 
source and destination volumes and determine if the appearance of its menu item 
needs to change. For example, a translator may need to change its menu item’s 
appearance if it is imported to another menu. After sending the trn_Appear 
message, Apple File Exchange sends a tm_Get message and updates the appearance 
of the translator’s menu item before displaying the new menu. 

It is possible for one disk to be both the source and destination for a translation. If the 
trnFrID and trnToID fields match and the trnFrVRef and trnToVRef fields match, the 
source and destination disks are the same. 

When a translator receives the tm_Appear message, it can also allocate global 
memory it needs before being activated. As discussed in the description of the 
tm_Init message, translators that use large amounts of global data can help to 
conserve memory by deferring memory allocation until they receive a trn_Activate, 
tm_Appear, or tm_File message, depending on the memory needs of the 
translator. In doing so, the translators avoid allocating memory before they actually 
use it. 

If a translator returns an error code as the function result, Apple File Exchange sends a 
tm_Set message to set the Gray flag and clear the Active flag in the translator’s status. 
This unchecks the translator’s menu item and makes it appear gray in the menu. 


trn_Appear 
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For each trn_Appear message, there is not always a matching trn_Disappear 
message. For example, a user clicking the Drive button in the Apple File Exchange 
window can switch to a second disk whose file system is the same as the first. This is 
what happens: 

□ Because the source and destination file systems remain the same, the translator 
menu(s) remain unchanged, and no tm_Disappear message is sent. 

□ Because the user has selected a new source or destination disk, a tm_Appear 
message is sent. 

See also trn_Activate, trn_Disappear, trn_Get, and trn_Init. 
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Description 

When sent 

Input 


Output 

Notes 


See also 


trn_Deactivate—deactivate the translator 


The tm_Deactivate message informs a translator that its menu item is no longer 
active and requests an updated translator status. 


This message is sent when the user, without holding down the Option key, selects a 
translator whose menu item is checked. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData 

trnFrID 

trnLogProc 

trnToData 

trnToID 


Pointer to global data for the source file system 

Resource ID for the source file system 

Pointer to the User Log procedure 

Pointer to global data for the destination file system 

Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


The translator updates its status flags and returns them as the function result. 


For many translators, the only action required in response to a trn_Deactivate 
message is to clear the Active flag in their status flags and return the new status as the 
function result. Note, however, that translators are not required to clear the Active 
flag in response to this message. For example, a translator that must always be active 
would never clear the Active flag. 

Only the tm_Activate message is sent when a default translator is chosen; no 
tm_Deactivate message is ever sent for a default translator. 


. trn_Activate. 
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Description 

When sent 

Input 

Output 

Notes 

See also 


tm_Disappear—respond to disappearance of menu 

The tm_Disappear message informs a translator that a menu containing its menu 
item has disappeared from the menu bar. 


The tm_Disappear message is sent when the user selects a different source or 
destination disk and, in so doing, changes the source or destination file system. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData 

trnFrID 

trnLogProc 

trnToData 

trnToID 


Pointer to global data for the source file system 

Resource ID for the source file system 

Pointer to the User Log procedure 

Pointer to global data for the destination file system 

Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


None. 


When translators receive the tm_Disappear message, they may choose to dispose of 
any global memory they allocated during a translation or when they appeared. 


trn_Appear. 
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trn_FiIe—translate a file 


Description 


When sent 


Input 


Output 


The tm_File message requests a translator to convert a file and move it to its new 
destination. 


The tm_File message is sent when the user clicks the Translate button in the Apple File 
Exchange window or in the Rename dialog box. 


Apple File Exchange passes a pointer to the translation parameter block in the Param 
parameter. For this message, the translation parameter block includes these values: 

trnAccepted If the tmTested field is TRUE, indicates whether a file was accepted 
for translation 


trnCountry 

trnFrData 

trnFrID 

trnFrPar 

trnFrVRef 


Country code for the version of the Macintosh on which Apple File 
Exchange is running 

Pointer to global data for the source file system 
Resource ID for the source file system 

Parent ID of the directory containing the file to be translated 
Volume reference for the source disk 


trnLogProc Pointer to the User Log procedure 
trnNamesAA.nameCnt 

Number of destination files for the translation. (In the current 
release of Apple File Exchange, this field always contains one.) 
trnNamesAA.namesfO] 

Name of the file to be translated 
trnNamesAA.namestll 

Name of the destination file for the translation 
trnStatProc Pointer to the Status procedure 

trnTested Indicates whether the translator has already been sent a 

trn_Recognize message for a file; if the value of tmTested is TRUE, 
the translator does not have to determine again if it can translate the 
file 


trnToData 

trnToID 

trnToPar 

trnToVRef 


Pointer to global data for the destination file system 

Resource ID for the destination file system 

Parent ID of the directory where the file to be translated will be 
copied 

Volume reference for the destination disk 


The translator must return one of these function results: 

□ Accept (= 0) if the translator accepted the file and either translated the file or could 
not translate the file for a reason outside its control (see “Notes" below) 

□ Unaccept (= 1) if it did not accept the file or discovered that it was not able to 
translate the file 

□ TmCancel (= 2) if the translator called the CallStatus function while translating (see 
“Notes” below) and received FALSE as a result 


trn_File 
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Notes 


See also 


The tm_File message is only sent to translators whose Active status flag is set. 

To determine if it accepts a file, the translator must use the same algorithm it uses 
when sent the tm_Recognize message. A translator can often save a step by looking at 
the trnTested and trnAccepted fields in the translation parameter block: 

□ The trnTested field is TRUE if the translator has already tried to recognize the file. 

□ If the value of the trnTested field is TRUE, the trnAccepted field indicates whether 
the translator accepted the file. 

There are no restrictions on the way a translator converts a file or moves the file to its 
destination. 

As it translates a file, a translator must periodically call the CallStatus function to 
inform the user of its progress. This procedure, described in Chapter 2 in the section 
“Calls From Translators to Apple File Exchange," accepts as input both a string 
containing information about the translation and a percent-complete value for the 
translation. If CallStatus returns FALSE, the user has canceled the translation. If this 
happens, the translator must close and delete any files it has created and return 
TrnCancel (= 2) as the function result. 

If an error occurs while translating a file, the translator must inform the user by calling 
the CallLog or CallErrLog procedure. These procedures are described in Chapter 2 in 
the section “Calls From Translators to Apple File Exchange.” 

In the event that an error outside the control of the translator (such as a disk error) 
prevents a file from being translated, the translator should return Accept. Because the 
same error will likely prevent other translators from translating the file, returning 
Accept keeps other translators from attempting the translation. 

If a translator discovers it cannot translate a file because it recognized the wrong file, 
or because of an error in the translator itself, it should return Unaccept and put an 
entry in the User Log. When, in the current version of Apple File Exchange, a 
translator returns Accept or Unaccept, no other translator will attempt the 
translation. 

When it receives the trn_File message, a translator can allocate any global memory it 
needs before translating a file. As discussed in the description of the tm_Init 
message, translators that use large amounts of global data can help to conserve 
memory by deferring memory allocation until they receive a trn_Activate, 
tm_Appear, or tm_File message, depending on the memory needs of the 
translator. In doing so, the translators avoid allocating memory before they actually 
use it. 


trn_Recognize. 
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trn_Finis—perform cleanup on exit 


Description 

When sent 

Input 


Output 

Notes 


The trn_Finis message requests a translator to dispose of any global memory it has 
allocated. 


This message is sent when the user 
a removes the translator’s menu item from a menu 
□ quits Apple File Exchange 

Future versions of Apple File Exchange may also send the message at other times. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData 

trnFrID 

trnLogProc 

trnToData 

trnToID 


Pointer to global data for the source file system 

Resource ID for the source file system 

Pointer to the User Log procedure 

Pointer to global data for the destination file system 

Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


None. 


The tm_Finis message is never sent to a translator if the translator’s initialization 
failed. 


trn.Finis 
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trn_Get—return current status of translator 


Description 
When sent 
Input 
Output 


The tm_Get message is sent to obtain the current status of a translator. 


This message is sent after each tm_Appear and trn_Init message. 


None. 


The translator returns its status flags as the function result. For descriptions of the 
status flags, see “The TranslateData Parameter” section in Chapter 2. 
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Description 
When sent 

Input 

Output 

Notes 


See also 


tm_GetSetting$—provide current settings 

The tm_GetSettings message requests a handle to the current settings for a translator. 

This message is sent when the user selects the Save Settings As menu item from the File 
menu. 


None. 


A translator with settings must return a handle to its settings as the function result. 
Translators that have no settings must return 0 as the function result. 


Some translators provide a dialog box that allows users to specify one or more 
translator settings. By choosing the Save Settings As dialog box, users can save these 
settings in Apple File Ex c h a n ge documents. Saved settings take effect when an 
Apple File Exchange document is opened or when a user chooses the Restore Settings 
From menu item and selects a file containing settings. The tm_GetSettings message 
requests the current settings for a translator. 

To save any settings necessary, a translator can call the NewHandle routine to create a 
block of the appropriate size and put the data in the block that is created. Apple File 
Exchange disposes of the handle that is passed to it; a translator must not dispose of 
it. 

There are no requirements for the settings a translator saves. Moreover, not all 
translators have settings. Translators that have no settings must return 0 as the 
function result. 

Apple File Exchange saves the status flags for each translator with the translator’s 
settings. 


trn_SetSettings. 


trn_GetSettings 
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trnjnit—initialize the translator 


Description 
When sent 

Input 


Output 


The trnjnit message requests a translator to initialize any variables that it uses. 

The tm_Init message is sent when 

□ Apple File Exchange is opened 

□ the translator is imported to another menu 

□ the menu item for a translator that has been removed from its original menu is 
returned to the menu 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData 

trnFrID 

trnLogProc 

trnToData 

trnToID 


Pointer to global data for the source file system 

Resource ED for the source file system 

Pointer to the User Log procedure 

Pointer to global data for the destination file system 

Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


The translator returns one of two values in the TranslateData parameter: 

□ If the translator needs no more than four bytes of global data, it can store the data 
in the TranslateData parameter. Most translators use the TranslateData parameter 
to store the default value for the translator status. 

□ If a translator requires more than four bytes of global data, it can allocate some 
relocatable memory and store a handle to it in TranslateData. 

Apple File Exchange passes the value stored in TranslateData back to the translator 

with each subsequent message. 

The translator must also return a function result: 

□ The value 0 if the translator was initialized successfully. 

Q An error code (typically a memory allocation error) if the initialization was not 
successful. If a translator returns an error code, its menu item is not displayed. 
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Notes 


See also 


If initialization of a translator is not successful, the translator must put an error 
message in the User Log in addition to returning an error code. 

Translators that vise large amounts of global data can help to conserve memory by 
deferring memory allocation until they receive a trn_Activate, trn_Appear, or 
tm_File message, depending on the memory needs of the translator. In doing so, 
translators avoid allocating memory before they actually need it. 

Apple File Exchange keeps separate copies of TranslateData for translators that are 
imported to other menus. This means that translators that appear in more than one 
menu are treated like separate translators. For these translators to respond properly 
to a message, they need only use the TranslateData value supplied with the message. 

Translators should normally work in any menu to which they are imported. Some 
translators, however, may not work properly when imported. Such translators can do 
the following to see what menu they are being moved to: 

□ Call GetResource to get handles to the source and destination file systems. 

□ Using the handles, call GetResInfo to get the resource name for each file system. 

□ Look at the last two characters in each resource name. These characters identify the 
file system. 

If a translator will not work if imported to the new menu, it should notify the user by 
displaying an alert box. In addition, the translator can return an error code to 
prevent its menu item from being displayed. 


trn_Appear. 
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trn_Load—load resources 


Description 

When sent 

Input 


Output 

Notes 


The tmJLoad message requests a translator to load any resources it needs from the 
disk containing Apple File Exchange. 


This message is sent to active translators when the user ejects the disk containing 
Apple File Exchange. This can occur often when users have only one or two disk 
drives. 


The Param parameter contains a pointer to the translation parameter block. For this 
message, the parameter block includes these values: 


trnFrData 

trnFrID 

trnLogProc 

trnToData 

trnToID 


Pointer to global data for the source file system 

Resource ID for the source file system 

Pointer to the User Log procedure 

Pointer to global data for the destination file system 

Resource ID for the destination file system 


All other values in the translation parameter block for this message are undefined. 


None. 


By loading resources it needs before a user ejects the Apple File Exchange disk, a 
translator can help users avoid swapping disks. 


3-16 


trn_Load 





trn_NewName—give file a new name 

Description The tm_NewName message requests a new name for a file. 


When sent The tm_NewName message is sent 

□ before Apple File Exchange translates a file 

□ when a file is renamed 

Input Apple File Exchange passes a pointer to the translation parameter block in the Param 

parameter. For this message, the translation parameter block includes these values: 

trnAccepted If the tmTested field is TRUE, indicates whether a file was accepted 
for translation 

trnFrData Pointer to global data for the source file system 

trnFrID Resource ID for the source file system 

trnFrPar Parent ID of the directory containing the file to be translated 

trnFrVRef Volume reference for the source disk 
trnLogProc Pointer to the User Log procedure 

trnNamesAA.namestO] 

Name of the file to be translated 
trnN ames a a . nameCnt 

The value 1, which is the number of destination files created. 
Because the current version of Apple File Exchange can only create 
a single destination file, do not change this value 

trnTested Indicates whether the translator has already been sent a 

trn_Recognize message for a file; if the value of trnTested is TRUE, 
the translator does not have to determine again if it can translate the 
file 

trnToData Pointer to global data for the destination file system 
trnToID Resource ID for the destination file system 

trnToPar Parent ID of the directory where the file to be translated will be 

copied 

trnToVRef Volume reference for the destination disk 

All other values in the translation parameter block for this message are undefined. 

Output The translator must return one of two function results: 

□ Accept (= 0) if the translator recognized the file to be translated 

□ Unaccept (= 1) if it did not recognize the file to be translated 

If the translator accepts the file, it must also return a new name for the destination file. 
The new name is returned in the field tmNamesAA. n ames[l]. 


trn_NewName 
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Notes 


See also 


The tm_NewName message is only sent to translators whose Active status flag is set. 

To determine if it accepts a file, the translator must use the same algorithm it uses 
when sent the trn_Recognize message. A translator can often save a step by looking at 
the trnTested and trnAccepted fields in the translation parameter block: 

□ The trnTested field is TRUE if the translator has already tried to recognize the file. 

□ If the value of the trnTested field is TRUE, the trnAccepted field indicates whether 
the translator accepted the file. 

When it accepts the file, the translator has the responsibility for selecting a new name 
for a file: 

□ It can select a new name itself. 

□ It can let the new file system provide an appropriate name by calling the file 
system’s FFMakeFName routine. (File system routines are described in Chapter 2 in 
the section “Calls From Translators to File Systems” and in Chapters 4 and 5). 

Translators must not interrupt the user to ask for a new name. It is up to the translator, 
not the user, to suggest a new name. Afterward, the user can replace the suggested 
name with a different one. 

Translators must also check to see if a new name is an appropriate one for the new file 
system. They can do this by calling the new file system’s FFOKFName routine. 

When translating files whose source and destination file system is the same, a 
translator can receive the tm_NewName message. This can occur when the source 
and destination files are of entirely different types (for example, a database file being 
translated to a text file), and the new file requires a different name or file extension. 

Users have the final say in selecting new filenames. Apple File Exchange gives them an 
opportunity to change the names that are suggested, and they may change names to 
suit their needs or to avoid conflicts with existing names. 


trn_Recognize. 
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trn_Recognize—determine if file can be translated 


Description 


When sent 


input 


Output 


Notes 


The tm_Recognize message requests an active translator to examine a file and to 
determine if it can translate the file. 


This message is sent when the Show Only Eligible Files menu item 

□ is selected 

□ is checked and a translator is activated or deactivated 

□ is checked and the user opens another directory 


The Param parameter contains a pointer to the translation parameter block. The 
parameter block includes these values: 


trnAccepted If the tmTested field is TRUE, indicates that the translator receiving 
the trn_Recognize message has already recognized the file 

trnFrData Pointer to global data for the source file system 

trnFrID Resource ID for the source file system 

trnFrPar Parent ID of the directory containing the file to be translated 

trnFrVRef Volume reference for the disk containing the file to be translated 

trnLogProc Pointer to the User Log procedure 
trnNamesAA.nameslO] 

Name of the file to be translated 


tmTested Indicates whether the translator has already been sent a 

tm_Recognize message for a file. Normally FALSE; if TRUE, the 
translator does not have to determine again if it can translate the file 


For this message, all other fields in the translation parameter block are undefined. 


The translator must return one of two function results: 

□ Accept (= 0) if the translator recognized the file to be translated 

□ Unaccept (= 1) if it did not recognize the file to be translated 


The trn_Recognize message is only sent to translators whose Active status flag is set. 

If more than one special-purpose translator (that is, a translator whose resource ID is 
greater than 2000) recognizes a file, Apple File Exchange displays a dialog box that 
allows the user to select which translator to use. This dialog box appears after the user 
has selected the file(s) to translate and then selects the Translate button. If only one 
special-purpose translator recognizes a file, that translator is used to translate the file. 
If only general-purpose translators (those with resource IDs less than or equal to 2000) 
recognize a file, the translator with the highest resource ID is used to translate the file. 

The criteria a translator uses to recognize a file depend on the nature of the 
translation. See the section “Recognizing Files” in Chapter 2 for information about 
choosing recognition criteria. 


trn_Recognize 
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Description 
When sent 

Input 

Output 
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tm_Set—set status of translator 

The tm_Set message is sent to change the translator’s status flags. 


In the current version of Apple File Exchange, the tm_Set message is sent 

□ to set the Active flag for default translators (those with a resource ED of 0) 

□ to clear the Active flag and set the Gray flag for translators that return an error 
message in response to a tm_Appear message 

□ to set the translator’s status flags after a user selects the Restore Settings From menu 
item 

The Param parameter contains the new status flags for the translator. For descriptions 
of the status flags, see “The TranslateData Parameter” section in Chapter 2. 


None. 


Set 




Description 
When sent 

Input 

Output 

Notes 


See also 


trn_$etSettings—set translator settings 


The tm_SetSettings message provides a handle to a new set of translator settings. 


The tm_SetSettings message is sent when the user selects the Restore Settings From 
item from the File menu. 


A handle to the translator’s new settings is passed in the Param field of the translation 
parameter block. 


None. 


Some translators provide a dialog box that allows users to specify one or more 
translator settings. By choosing the Save Settings As dialog box, users can save these 
settings in Apple File Exchange documents. Saved settings take effect when an Apple 
File Exchange document is opened or when a user chooses the Restore Settings From 
menu item and selects a file containing settings. 

The trn_SetSettings message provides the translator a handle to saved settings. The 
translator can then update its own internal copy of the settings and refer to them when 
it translates files. Apple File Exchange disposes of the handle it passes; a translator 
must not dispose of it. 

Apple File Exchange saves the status flags for each translator with the translator’s 
settings. After sending a tm_SetSettings message, Apple File Exchange issues a 
tm_Set message to restore the saved status flags. 


trn_GetSettings. 


trn_SetSettings 


3-21 


















. 














Chapter 4 


Calling the 
ProDOS File System 
From Translators 






This chapter describes the ProDOS foreign file system provided by Apple File 
Exchange. It includes 

□ an overview of the ProDOS file system and the interface that Apple File Exchange 
provides to ProDOS 

□ a list of the limitations of the ProDOS file system 

□ details of the ways in which the operations provided by the ProDOS file system 
differ from the corresponding Macintosh Hierarchical File System (HFS) rails 

To use the ProDOS foreign file system, you must be familiar with ProDOS file 
operations and with the Macintosh HFS calls. For information about ProDOS, see the 
ProDOS Technical Reference Manual. For information about HFS, see “The File 
Manager” chapter in Volume IV of Inside Macintosh. 


About the ProDOS file system 

ProDOS is the Professional Disk Operating System used on the Apple II family of 
computers. ProDOS provides a hierarchical, tree-structured file system that is similar 
in many ways to the Macintosh HFS. 

Translators should never try to read ProDOS disk structures directly. Instead, they 
must use the ProDOS foreign file system resource provided by Apple File Exchange. 
There are two important reasons for using this resource: 

1. Apple File Exchange can properly handle disk swapping and other events. 

2. Translators use a single function, CallFS, to perform any of the operations provided 
by the file system. The operation performed is determined by the value of the 
CallFS Msg parameter. 

Translators also use the CallFS function to call the other file systems supported by 
Apple File Exchange. The calls provided by CallFS are modeled after Macintosh HFS 
calls and are the same for all file systems. Because there are important differences 
between the ProDOS and HFS file systems, the results of many ProDOS calk are 
different from the corresponding HFS calls. When there are differences, the 
differences are explained in the next section and in the descriptions of the calls. 
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Limitations of the ProDOS file system 

The ProDOS foreign file system has a number of limitations that apply to all calls: 

□ Working directories are not implemented in any form. All volume reference 
numbers must refer to actual volumes, not directories within volumes. 

□ Partial pathnames are not supported. The ProDOS file system recognizes only 
volume names and filenames. 

□ A maximum of eight files may be open at any one time. 

□ ProDOS operations are always performed synchronously. The IoCompletion field 
of the parameter block is always ignored. The Async parameter in file system calls is 
also ignored. 

□ The root directory of every volume has a directory ID of 2. 

□ All calls support filenames, but not pathnames. For example, 

HD:MyFolder:MyFile cannot be passed as a parameter to a ProDOS file system 
routine, but MyFile can. 

a As with all Apple File Exchange file systems, the HFS version of each call is the one 
that is implemented. You must pass pointers to PBHParamBlockRec records where 
appropriate and include values in all the fields that are necessary for each rail 


File system calls not supported by the ProDOS file system 

Table 2-7 in Chapter 2 lists all the available file system calls and the corresponding 
Msg value for each call. Table 4-1 lists those calls that are not supported by the 
ProDOS file system. 


Table 4-1 

File system calls not supported 
by the ProDOS file system 

Name of call Msg value 


FFAllocate 19 

FFAllocContig 20 

FFCloseWD 36 

FFGetWDInfo 37 

FFLockRange 11 

FFOpenRF 10 

FFOpenWD 35 

FFRstFLock 29* 

FFSetFLock 28* 

FFSetFVers 30 

FFSetVInfo 2 

FFUnlockRange 12 


'Note that you can lock and unlock 
files by using the FFSetCatlnfo call. 


Limitations of the ProDOS file system 
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ProDOS file system calls 

The following sections describe the differences between ProDOS foreign file system 
calls and the corresponding Macintosh HFS calls. 


FFCIose 

The FFCIose call behaves like the corresponding Macintosh call. 


FFCreate 

The FFCreate call creates a binary file (ProDOS file type $06). To set another type, you 
must issue a FFSetFInfo or FFSetCatlnfo call. To set the auxiliary file type and access 
bits for the file, use the FFXSetCatlnfo call. 

If the name of the file created does not conform to ProDOS conventions, the FFCreate 
call will fail and return the error “Bad filename.” 

FFCreate may fail with the error -9 if the file’s full pathname is greater than the ProDOS 
limit of 64 characters. 


FFDelete 

The FFDelete call behaves like the corresponding Macintosh call. 


FFDirCreate 

The FFDirCreate call behaves like the corresponding Macintosh call. 

If the name of the directory created does not conform to ProDOS conventions, the 
FFDirCreate call will fail and return the error “Bad filename.” 

FFDirCreate may fail with the error “Bad filename” if the directory’s full pathname is 
greater than the ProDOS limit of 64 characters. 

❖ Note: Translators should only use FFDirCreate to create temporary directories 
during a translation. If a translator does create a directory, it must delete the 
directory before finishing the translation. 


FFFlushFile 

The FFFlushFile call behaves like the corresponding Macintosh call. 


FFFlushVol 

The FFFlushVol call behaves like the corresponding Macintosh call. 
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FFGetCatlnfo 

For the FFGetCatlnfo call, the following fields return the value 0 for files: 

□ ioFIFndrInfo 

□ fdLocation 

□ fdFldr 

□ ioFIStBIk 

□ ioFffiStBlk 

□ ioFIXFndrInfo 

□ ioFlRLgLen 

□ ioFIRPyLen 

□ ioFIBkDat 

The following fields return values other than 0 for files: 

□ ioNamePtr—if the file is specified by ioFDirlndex 

□ ioFRefNumber—if the file is open, this is the file reference number 
a ioFlAttrib—file attributes; reflects the ProDOS access bits: 

□ $01—if the file is locked 

□ All other bits are cleared. 

□ ioFIFndrInfo 

□ fdtype—a four-byte string that reflects the ProDOS file type. The string contains 
the ASCII equivalents for the two hexadecimal digits that make up the ProDOS file 
type followed by two blanks. For example, the fdtype field for an Applesoft 
program file ($FC) would be ' FC '. There is one exception.- the fdtype field 
for a TXT ($04) file is ' TEXT'. 

□ fdcreator—'pdos' 

□ fdFlags—All bits are cleared. 

□ ioDirlD—file number 

□ ioFILgLen—data fork logical length 

□ ioFIPyLen—data fork physical length 

□ ioFICrDat—creation date 

□ ioFlMdDat—modification date 

□ ioFlParlD—ID of parent of specified file (2 indicates that the parent is the root; 0 
indicates that the file is already at the root) 

□ ioFICIpSiz—512 

The following fields return the value 0 for directories: 

□ ioFRefNum 

□ ioDrUsrWds 

□ ioDrFndrlnfo 

□ ioDrBkDat 
Q ioFlAttrib 


ProDOS file system calls 
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The following fields return values other than 0 for directories: 

□ ioNamePtr—if directory is specified by ioFDirlndex 

□ ioDrDirlD—directory ID (root is indicated by 2) 

o ioDrNmFls—number of files and directories in this directory 

□ ioDrlCrDat—creation date 

□ ioDrMdDat—same as creation date 

□ ioDrParlD—ID of parent of specified file (2 indicates that the parent is the root; 0 
indicates that the file is already at the root) 

The PBGetCatlnfo function is powerful, but it may be difficult to understand. Here is a 
summary of what it does: 

□ ioFDirlndex = n (> 0) 

INPUT 

□ ioNamePtr—ignored for input 

□ ioDirlD—if 0, use ioVRefNum for volume and directory; otherwise, use ioDirlD 
for directory 

OUTPUT 

□ ioNamePtr^'—returns name of rzth file or directory 

□ ioDirlD—returns file number (ioFlNum) or directory number (ioDrDirlD) 

□ ioFlParlD—returns directory number of parent of nth file or directory 

□ ioFDirlndex = 0 
INPUT 

□ ioNamePtr/'—contains name of file in question (error if ioNamePtr = NIL) 

□ ioDirlD—if 0, use ioVRefNum for volume and directory; otherwise, use ioDirlD 
for directory 

OUTPUT 

□ ioNamePtr/'—unchanged 

□ ioDirlD—returns file number (ioFlNum) or directory number (ioDrDirlD) 

□ ioFlParlD—returns directory number of parent of file or directory in question 

□ ioFDirlndex = -1 
INPUT 

□ ioNamePtr—ignored 

□ ioDirlD—if 0, use ioVRefNum for volume and directory; otherwise, use ioDirlD 
for directory 

OUTPUT 

□ ioNamePtr/'—returns name of directory specified by ioVRefNum and ioDirlD 

□ ioDirlD—returns number of directory (ioDrDirlD) specified by ioVRefNum and 
ioDirlD 

□ ioFlParlD—returns directory number of parent of directory in question 

FFGetEOF 

The FFGetEOF call behaves like the corresponding Macintosh call. 
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FFGetFInfo 

For the FFGetFInfo call, the following fields return the value 0: 

□ ioFlFndrlnfo 

□ fdLocation 

□ fdFldr 

□ ioFIStBIk 

□ ioFlRStBlk 

□ ioFIRLgLen 

□ ioFIRPyLen 

The following fields return values other than 0: 

□ ioNamePtr—if the file is specified by ioFDirlndex 

□ ioFRefNumber—if the file is open, file reference number 

□ ioFlAttrib—file attributes; reflects the ProDOS access bits: 

□ $01—if the file is locked 

□ All other bits are cleared. 

□ ioFlFndrlnfo 

□ fdtype—a four-byte string that reflects ProDOS file type. The string contains the 
ASCH equivalents for the two hexadecimal digits that make up the ProDOS file 
type followed by two blanks. For example, the fdtype field for an Applesoft 
program file ($FC) would be ' FC '. There is one exception: the fdtype field 
for a TXT' ($04) file is ' TEXT'. 

□ fdcreator—'pdos' 

□ fdFlags—all bits are cleared 

□ ioDirlD—file number 

□ ioFILgLen—data fork logical length 

□ ioFlPyLen—data fork physical length 
a ioFICrDat—creation date 

□ ioFlMdDat—modification date 


FFGetFPos 

The FFGetFPos call behaves like the corresponding Macintosh call. 


FFGetVInfo 

The FFGetVInfo call returns one of the following as the function result: 

□ If the value passed in the ioVolIndex field is greater than 0, the call returns an error. 

□ If the value passed in the ioVolIndex field is equal to 0, the call returns information 
about the volume specified by ioVRefNum. 

□ If the value passed in the ioVolIndex field is less than 0, the call uses ioNamePtr and 
ioVRefNum in the standard way. 


ProDOS file system calls 
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The following fields return 0: 

□ ioAllocPtr 

□ ioVNxtCNID 

□ ioVFSID 

□ ioVSeqNum 

□ ioVWrCnt 

□ ioVFndrlnfo 

□ ioVAtrb 

□ ioVNmFls 

□ ioVBitMap 

□ ioAlBISt 

□ ioVSigWord 

□ ioVDrvInfor 

□ ioVDRefNum 

□ ioVFilCnt 

□ ioVDirCnt 

The following fields return information: 

□ ioNamePtr—if ioVRefNum is used to specify a volume, returns name of volume 
specified 

□ ioVRefNum—if ioNamePtr or drive number is used to specify a volume, returns 
reference number of volume 

□ ioVCrDate—volume creation date 

□ ioVLsMod—same as the volume creation date, or the volume creation date + 1 if 
the ProDOS access bit indicates that the volume has been changed 

a ioVNmAlBlks—number of allocation blocks 

□ ioVAlBlkSiz—512 

□ ioVClpSiz—512 

□ ioVFrBlk—number of unused allocation blocks 

□ ioVBkUp—same as creation date 


FFMakeDName 

The FFMakeDName call accepts the following fields from a HParamBlockRec record as 
input: 

□ ioNamePtr—a pointer to a directory name 

□ ioVRefNum—the volume reference number for the volume containing the directory 

□ ioFlParlD—ID of the specified directory’s parent 

The FFMakeDName call converts the name pointed to by ioNamePtr into a legal 
ProDOS directory name. 

This call does not check to see if the directory name already exists. 
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FFMakeFName 

The FFMakeFName call accepts the following fields as input: 

□ ioNamePtr—a pointer to a filename 

□ ioVRefNum—the volume reference number for the volume containing the file 

□ ioFIParlD—ID of the specified file’s parent 

The FFMakeFName call converts the name pointed to by ioNamePtr into a legal 
ProDOS filename. 

This call does not check to see if the filename already exists. 


FFOKDName 

The FFOKDName call accepts the following fields as input 

□ ioNamePtr—a pointer to a directory name 

□ ioVRefNum—the volume reference number for the volume containing the directory 

□ ioFIParlD—ID of the specified directory’s parent 

The FFOKDName call returns noErr if the name pointed to by ioNamePtr is a legal 
ProDOS directory name. 

This call does not check to see if the directory name already exists. 


FFOKFName 

The FFOKFName call accepts the following fields as input: 

□ ioNamePtr—a pointer to a filename 

Q ioVRefNum—the volume reference number for the volume containing the file 

□ ioFIParlD—ID of the specified file’s parent 

The call returns noErr if the name pointed to by ioNamePtr is a legal ProDOS 
filename. 

This call does not check to see if the filename already exists. 


FFOpen 

The FFOpen call behaves like the corresponding Macintosh call, with one exception: 
the ioPermssn field must always be 0. 


FFRead 

The FFRead call behaves like the corresponding Macintosh rail 


ProDOS file system calls 
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FFRename 

If the new name does not follow the ProDOS convention, the FFRename call will fail 
and return a “Bad filename,” “Bad directory name,” or “Bad volume name” error. 


FFSetCatlnfo 

For the FFSetCatlnfo call, the following fields are ignored for files: 

□ ioFlFndrlnfo 

□ fdLocation 

□ fdFldr 

□ fdFlags 

□ ioFlXFndrlnfo 

□ ioFICIpSiz 

□ ioFIBkDat 

The following fields may be set for files: 
a ioFlFndrlnfo 

□ fdtype—a four-byte string that reflects ProDOS file type. The string contains the 
ASCn equivalents for the two hexadecimal digits that make up the ProDOS file 
type followed by two blanks. For example, the fdtype field for an Applesoft 
program file ($FC) would be ' FC '. There is one exception: the fdtype field 
for a TXT ($04) file is ' TEXT'. If the fdtype string does not follow this 
convention, the file type is not changed. {Note: To set the auxiliary file type for a 
ProDOS file, use the FFXSetCatlnfo call.) 

□ fdcreator—'pdos' 

□ ioFICrDat—creation date 

□ ioFlMdDat—modification date 

□ ioFlAttrib—If this field is set to $01, sets the file locked attribute for the file. 

The following fields are ignored for directories: 

□ ioDrUsrWds 

□ ioDrFndrlnfo 

□ ioDrMdDat 

□ ioDrBkDat 

The following fields may be set for directories: 

□ ioNamePtr—if a directory is specified by ioFDirlndex 

□ ioDrCrDat—creation date 


FFSetEOF 

The FFSetEOF call works the same as on the Macintosh. 
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FFSetFInfo 

For the FFSetFInfo call, the following fields are ignored: 

D ioFIFndrInfo 

□ fdLocation 

□ fdFldr 

The following fields may be set: 

□ ioFIFndrInfo 

□ fdtype—a four-byte string that reflects ProDOS file type. The string contains the 

ASCn equivalents for the two hexadecimal digits that make up the ProDOS file 
type followed by two blanks. For example, the fdtype field for an Applesoft 
program file ($FC) would be ' FC 1 . There is one exception: the fdtype field 

for a TXT ($04) file is ' TEXT'. If the fdtype string does not follow this 
convention, the file type is not changed. 

□ ioFICrDat—creation date 


FFSetFPos 

The FFSetFPos call behaves like the corresponding Macintosh call. 


FFWrite 

The FFWrite call behaves like the corresponding Macintosh call. To greatly increase 
the efficiency of this call, write in 512-byte blocks. 
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FFXGetCatlnfo 

The FFXGetCatlnfo call uses the XCInfoPBRec record described below: 


XCInfoPBRec = RECORD 
CInfo : CInfoPBRec; 

{Input to FFXGetCatlnfo. This is the same record used by 
FFGetCatlnfo, and you can use this call to perform all the functions 
of FFGetCatlnfo) 

CASE xfs : XFSType OF 

prodos : 

(These fields are returned by FFXCatlnfo) 

(auxtype : INTEGER; 
access : SIGNEDBYTE; 
storagetype : SIGNEDBYTE; 
version : SIGNEDBYTE; 
minvers : SIGNEDBYTE) 

END; 

The case selector for this variable record is defined as follows: 

TYPE 


XFSType =■ (Mac, ProDOS, MSDOS) ; 

The fields in this record are used as described below: 

CInfo The standard CInfoPBRec record used by the FFGetCatlnfo and 

FFSetCatlnfo calls; using this record, you can perform any of the 
functions provided by the FFGetCatlnfo call 

auxtype The auxiliary file type for a ProDOS file 

access Contains flags that control access to a ProDOS file: 

$80—the file can be deleted 

$40—the file can be renamed 

$20—the file has changed since it was last backed up 

$02—the file can be written to 

$01—the file can be read 

storagetype Describes the ProDOS directory entry for the file: 

$1—the file is a seedling (that is, it has only one data block) 

$2—the file is a sapling (that is, one containing from 2 to 256 data 
blocks) 

$3—the file is a tree (that is, one containing from 257 to 32768 data 
blocks) 

$D—the file is a subdirectory 

version The version of ProDOS under which this file was created 

minvers The minimum version of ProDOS that can gain access to this file 
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Chapter 5 


Calling the 
MS-DOS File System 
From Translators 



This chapter describes the MS-DOS foreign file system provided by Apple File 
Exchange. It includes 

□ an overview of the file system and its operation 

□ a list of the file system’s limitations 

□ details of the ways in which MS-DOS file system calls differ from the corresponding 
Macintosh Hierarchical File System (HFS) calls. For information about HFS, see 
“The File Manager” chapter in Volume IV of Inside Macintosh. 


About the MS-DOS file system 

MS-DOS is the operating system created by Microsoft for the IBM PC and compatible 
computers. Recent versions of MS-DOS provide a hierarchical, tree-structured file 
system that is similar in many ways to the Macintosh Hierarchical File System (HFS). 
Apple File Exchange supports versions of MS-DOS numbered 2.0 and higher. 

Translators should never try to read MS-DOS disk structures directly. Instead, they 
must use the MS-DOS foreign file system resource provided by Apple File Exchange. 
There are two important reasons for using this resource: 

1. Apple File Exchange can properly handle disk swapping and other events. 

2. Translators use a single function, CallFS, to perform any of the operations provided 
by the file system. The operation performed is determined by the value of the 
CallFS Msg parameter. 

Translators also use the CallFS function to call the other file systems supported by 
Apple File Exchange. The calls provided by CallFS are modeled after Macintosh HFS 
calls and are the same for all file systems. Because there are important differences 
between the MS-DOS and HFS file systems, the results of many MS-DOS calls are 
different from the corresponding HFS calls. When there are differences, the 
differences are explained in the next section and in the descriptions of the calls. 

If you have already read Chapter 4, you will notice that the MS-DOS foreign file system 
is very similar to the ProDOS foreign file system. Although many of the descriptions in 
this chapter are identical to those in Chapter 4, there are important differences 
between the ProDOS and MS-DOS versions of certain calls . Before using any MS-DOS 
routine, be sure to read its description carefully. 
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Limitations of the MS-DOS file system 

The MS-DOS file system has a number of limitations that apply to all calls: 

□ Working directories are not implemented in any form. All volume reference 
numbers must refer to actual volumes, not directories within volumes. 

□ Partial pathnames are not supported. The MS-DOS file system recognizes only 
volume names and filenames. 

□ A maximum of eight files may be open at any one time. 

□ MS-DOS operations are always performed synchronously. The IoCompletion field 
of the parameter block is always ignored. The Async parameter in file system calls is 
also ignored. 

□ The root directory of every volume has a directory ID of 2. 

□ All calls support filenames, but not pathnames. For example, 

HD:MyFolder:MyFile cannot be passed as a parameter to an MS-DOS file system 
routine, but MyFile can. 

□ As with all Apple File Exchange file systems, the HFS version of each call is the one 
that is implemented. You must pass pointers to PBHParamBlockRec records where 
appropriate and include values in all the fields that are necessary for each call. 


File system calls not supported by the MS-DOS file system 

Table 2-7 in Chapter 2 lists all the available file system calls and the corresponding 
Msg value for each call. Table 5-1 lists those calls that are not supported by the 
MS-DOS file system. 


Table 5-1 

File system calls not supported 
by the MS-DOS file system 

Name of call Msg value 


FFAllocate 19 

FFAllocContig 20 

FFCloseWD 36 

FFGetWDInfo 37 

FFLockRange 11 

FFOpenRF 10 

FFOpenWD 35 

FFRstFLock 29* 

FFSetEOF 18 

FFSetFLock 28* 

FFSetFVers 30 

FFSetVTnfo 2 

FFUnlockRange 12 

•Note that you can lock and unlock 
files by using the FFSetCatlnfo call. 


Limitations of the MS-DOS file system 
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MS-DOS file system calls 

The following sections describe the differences between MS-DOS foreign file system 
calls and the corresponding Macintosh file system calls. 


FFCIose 

The FFCIose call behaves like the corresponding Macintosh call. 


FFCreate 

The FFCreate call creates a file. To set the attributes of a file, use the FFXSetCatlnfo 
call. 

If the name of the file created does not conform to MS-DOS conventions, the FFCreate 
call will fail and return the error “Bad filename.” 

FFCreate may fail with the error —9 if the file’s full pathname is greater than the 
MS-DOS limit of 64 characters. 


FFDelete 

The FFDelete call behaves like the corresponding Macintosh call. 


FFDirCreate 

The FFDirCreate call behaves like the corresponding Macintosh call. 

If the name of the directory created does not conform to MS-DOS conventions, the 
FFDirCreate call will fail and return the error “Bad filename.” 

FFDirCreate may fail with the error -9 if the directory’s full pathname is greater than 
the MS-DOS limit of 64 characters. 

Note: Translators should only use FFDirCreate to create temporary directories 
during a translation. If a translator does create a directory, it must delete the 
directory before finishing the translation. 


FFFlushFile 

The FFFlushFile call behaves like the corresponding Macintosh call. 


FFFlushVol 

The FFFlushVol call behaves like the corresponding Macintosh call. 
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FFGetCatlnfo 

For the FFGetCatlnfo call, the following fields return 0 for files: 

D ioFlFndrlnfo 

□ fdLocation 

□ fdFldr 

□ ioFIStBIk 

□ ioFIRStBIk 

□ ioFlXFndrlnfo 
a ioFIRLgLen 

□ ioFIRPyLen 

The following fields return values for files: 

□ ioNamePtr—if file is specified by ioFDirlndex 

□ ioFRefNumber—file reference number, if the file is open 

□ ioFlAttrib—file attributes; reflects the MS-DOS characteristic bits: 

□ $01—if the file is locked 

□ All other bits are cleared. 

□ ioFlFndrlnfo 

□ fdtype 

TEXT—if the file is determined to be a text file 
'BINA'—all other files 

Note: Like other MS-DOS files, MS-DOS text files do not have an explicit file type. 
FFGetFInfo uses the following algorithm to determine if a file is an MS-DOS text file: 

1. It reads the first 512 bytes of the file (or all of the file if it contains less than 512 
bytes). 

2. Next, it counts the number of printable characters (those characters between 
space and tilde in the ASCII character set) and compares the result to the number 
of nonprinting characters (all characters that aren’t in the range between space 
and tilde, including all characters whose high-order bits are set). 

3. If the number of printable characters is at least twice the number of nonprinting 
characters, it determines that the file is a text file. 

Because this algorithm does not always produce the correct result, translators must 
be prepared to handle cases where a file is incorrectly identified. 

□ fdcreator—'mdos' 

□ fdFlags—if the MS-DOS hidden attribute ($02 in byte 11 of an MS-DOS directory 
entry) is set for a file, the fdFlags invisible flag is set. If the MS-DOS system 
attribute ($04 in byte 11 of an MS-DOS directory entry) is set for a file, the fdFlags 
system flag is set. 

□ ioDirlD—file number 

□ ioFILgLen—data fork logical length 

□ ioFIPyLen—data fork physical length 

□ ioFICrDat—creation date 

□ ioFIBkDat—same as creation date 
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□ ioFlMdDat—same as creation date if the archive bit has not been changed, 
otherwise (creation date + 1) 

□ ioFlParlD—ID of parent of specified file (2 indicates parent is root; 0 indicates file 
is already at root) 

□ ioFICIpSiz—0 

The following fields return 0 for directories: 

□ ioFRefNum 

□ ioDrUsrWds 

□ ioDrFndrlnfo 

□ ioDrlCrDat 

□ ioDrMdDat 

□ ioDrBkDat 

□ ioFlAttrib 

□ ioDrBkDat 

The following fields return values for directories: 

□ ioNamePtr—if directory is specified by ioFDirlndex 

□ ioDrDirlD—directory ID (root is indicated by 2) 

□ ioDrNmFls—number of files and directories in this directory 

□ ioDrCrDat—creation data 

□ ioDrMdDat—same as creation date 

□ ioDrParlD—ID of parent of specified file (2 indicates the root; 0 indicates no 
parent, that is, this is already the root) 

The PBGetCatlnfo function is powerful, but it may be difficult to understand. Here is a 
summary of what it does: 

□ ioFDirlndex = n (> 0) 

INPUT 

□ ioNamePtr—ignored for input 

ioDirlD—if 0, use ioVRefNum for volume and directory; otherwise, use ioDirlD 
for directory 

OUTPUT 

□ ioNamePtr/'—returns name of nth file or directory 

□ ioDirlD—returns file number (ioFINum) or directory number (ioDrDirlD) 

□ ioFlParlD—returns directory number of parent of nth file or directory 

□ ioFDirlndex = 0 
INPUT 

□ ioNamePtr/'—contains name of file in question (error if ioNamePtr = NIL) 

□ ioDirlD—if 0, use ioVRefNum for volume and directory; otherwise, use ioDirlD 
for directory 

OUTPUT 

□ ioNamePtr A —unchanged 

□ ioDirlD—returns file number (ioFINum) or directory number (ioDrDirlD) 

□ ioFlParlD—returns directory number of parent of file or directory in question 
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□ ioFDirlndex = -1 
INPUT 

□ ioNamePtr—ignored 

□ ioDirlD—if 0, use ioVRefNum for volume and directory, else use ioDirlD for 
directory 

OUTPUT 

□ ioNamePtr''—returns name of directory specified by ioVRefNum and ioDirlD 

□ ioDirlD—returns number of directory (ioDrDirlD) specified by ioVRefNum and 
ioDirlD 

□ ioHParlD—returns directory number of parent of directory in question 


FFGetEOF 

The FFGetEOF call behaves like the corresponding Macintosh call. 


FFGetFInfo 

For the FFGetFInfo call, the following fields return 0: 

□ ioFlFndrlnfo 

□ fdLocation 

□ fdFldr 

□ ioFIStBIk 

□ ioFLRStBlk 

□ ioFlRLgLen 

□ ioFIRPyLen 

The following fields return values: 

□ ioNamePtr—if file is specified by ioFDirlndex 

□ ioFRefNumber—file reference number, if the file is open 

□ ioFlAttrib—file attributes; reflects the MS-DOS characteristic bits: 

□ $01—if the file is locked 

□ All other bits are cleared. 

□ ioFlFndrlnfo 

□ fdtype 

TEXT—if the file is calculated to be a text file 
'BINA'—all other files 

Note: Like other MS-DOS files, MS-DOS text files do not have an explicit file type. 
FFGetFInfo uses the following algorithm to determine if a file is an MS-DOS text file: 

1. It reads the first 512 bytes of the file (or all of the file if it contains less than 512 
bytes). 
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2. Next, it counts the number of printable characters (those characters between 
space and tilde in the ASCII character set) and compares the result to the number 
of nonprinting characters (all characters that aren’t in the range between space 
and tilde, including all characters whose high-order bits are set). 

3. If the number of printable characters is at least twice the number of nonprinting 
characters, it determines that the file is a text file. 

Because this algorithm does not always produce the correct result, translators must 
be prepared to handle cases where a file is incorrectly identified. 

□ fdcreator—'mdos' 

□ fdFlags—if the MS-DOS hidden attribute ($02 in byte 11 of an MS-DOS directory 
entry) is set for a file, the fdFlags invisible flag is set. If the MS-DOS system 
attribute ($04 in byte 11 of an MS-DOS directory entry) is set for a file, the fdFlags 
system flag is set. 

□ ioDirlD—file number 

□ ioFILgLen—data fork logical length 

□ ioFIPyLen—data fork physical length 

□ ioFICrDat—creation date 

□ ioFIBkDat—same as creation date 

□ ioFlMdDat—if the archive bit has not been changed, same as creation date 


FFGetFPos 

The FFGetFPos call behaves like the corresponding Macintosh call. 


FFGetVInfo 

The FFGetVInfo call returns one of the following as the function result; 

□ If the value passed in the ioVolIndex field is greater than 0, the call returns an error. 

□ If the value passed in the ioVolIndex field is equal to 0, the call returns information 
about the volume specified by ioVRefNum. 

□ If the value passed in the ioVolIndex field is less than 0, the call uses ioNamePtr and 
ioVRefNum in the standard way. 

The following fields return 0: 

□ ioVFndrlnfo 

□ ioVCrDat 

□ ioVLsMod 

□ ioVBitMap 

□ ioAllocPtr 

□ ioVNxtCNID 

□ ioVFSID 

□ ioVSeqNum 

□ ioVWrCnt 

□ ioVBkUp 
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□ ioVAtrb 

□ ioVNmFls 

□ ioVClpSiz 

□ ioVSigWord 

□ ioVDrvInfo 

□ ioVDRefNum 

□ ioVFilCnt 

□ ioVDirCnt 

The following fields return information: 

□ ioNamePtr—if ioVRefNum is used to specify a volume, returns name of volume 
specified 

□ ioVRefNum—if ioNamePtr or drive number is used to specify a volume, returns 
reference number of volume 

□ ioVNmAlBlks—number of allocation blocks 

□ ioVAlBlkSiz—allocation block size, same as cluster size for volume 

□ ioAlBISt—first block in volume block map 

□ ioVFrBlk—number of unused allocation blocks 


FFMakeDName 

The FFMakeDName call accepts the following fields from a HParamBlockRec record as 
input: 

□ ioNamePtr—a pointer to a directory name 

□ ioVRefNum—the volume reference number for the volume containing the directory 

□ ioFIParlD—ID of the specified directory’s parent 

The FFMakeDName call converts the name pointed to by ioNamePtr into a legal 
MS-DOS directory name. 

This call does not check to see if the directory name already exists. 


FFMakeFName 

The FFMakeFName call accepts the following fields as input: 

□ ioNamePtr—a pointer to a filename 

□ ioVRefNum—the volume reference number for the volume containing the file 

□ ioFIParlD—ID of the specified file’s parent 

The FFMakeFName call converts the name pointed to by ioNamePtr into a legal 
MS-DOS filename. 

This call does not check to see if the filename already exists. 
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FFOKDName 

The FFOKDName call accepts the following fields as input 

□ ioNamePtr—a pointer to a directory name 

□ ioVRefNum—the volume reference number for the volume containing the directory 

□ ioFIParlD—ID of the specified directory’s parent 

The FFOKDName call returns noErr if the name pointed to by ioNamePtr is a legal 
MS-DOS directory name. 

This call does not check to see if the directory name already exists. 


FFOKFName 

The FFOKFName call accepts the following fields as input: 

□ ioNamePtr—a pointer to a filename 

a ioVRefNum—the volume reference number for the volume containing the file 

□ ioFIParlD—ID of the specified file’s parent 

The call returns noErr if the name pointed to by ioNamePtr is a legal MS-DOS 
filename. 

This call does not check to see if the filename already exists. 


FFOpen 

The FFOpen call behaves like the corresponding Macintosh call. 


FFRead 

The FFRead call behaves like the corresponding Macintosh call. 


FFRename 

If the new name does not follow the MS-DOS convention, the FFRename call will fail 
and return a “Bad filename,’’ “Bad directory name,” or “Bad volume name” error. 


FFSetCatlnfo 

For the FFSetCatlnfo call, the following fields are ignored for files: 

□ ioFlFndrlnfo 

□ fdLocation 

□ fdFldr 

□ ioFIXFndrInfo 

□ ioFICIpSiz 
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The following fields may be set for files: 

□ ioFlAttrib—file attributes; reflects the MS-DOS characteristic bits 

□ $01—if the file is locked 

□ All other bits are cleared. 

□ ioFlFndrlnfo 

□ fdtype—The following file types are ignored: 

'TEXT', 'BINA', all nulls 

□ ioFlFndrlnfo 

□ fdcreator—'mdos' or all nulls (same as 'mdos') 

□ ioFICrDat—creation date 

□ ioFIBkDat—same as creation date 

□ ioFlMdDat—if the archive bit has not been changed, same as creation date 
The following fields are ignored for directories: 

□ ioDrUsrWds 

□ ioDrFndrlnfo 

□ ioDrCrDat 

□ ioDrMdDat 

□ ioDrBkDat 

□ ioFlAttrib 

□ ioNamePtr 


FFSetFInfo 

For the FFSetFInfo call, the following fields are ignored: 
a ioFlFndrlnfo 

□ fdLocation 

□ fdFldr 

□ fdtype 

□ fdcreator 

□ fdFlags 

The following fields may be set: 

□ ioFlFndrlnfo 

□ ioFICrDat—creation date 

□ ioFIBkDat—same as creation date 

□ ioFlMdDat—if the archive bit has not been changed, same as creation date 


FFSetFPos 

The FFSetFPos call behaves like the corresponding Macintosh call. 
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FFWrite 

The FFWrite call behaves like the corresponding Macintosh call. 


FFXGetCatlnfo 


The FFXGetCatlnfo call uses the XCInfoPBRec record described below: 

XCInfoPBRec = RECORD 
CInfo : CInfoPBRec; 

{Input to FFXGetCatlnfo. This is the same record used by FFGetCatlnfo, 
and you can use this call to perform all the functions of FFGetCatlnfo} 

CASE xfs : XFSType OF 

msdos : 


{These fields are returned by FFXGetCatlnfo} 
(attrib : SIGNEDBYTE; 
filler4 : SIGNEDBYTE) 


END; 

The case selector for this variable record is defined as follows: 

TYPE 


XFSType = (Mac, ProDOS, MSDOS); 

The fields in this record are used as described below. These fields cannot be changed 
by translators. 

CInfo The standard CInfoPBRec record used by the FFGetCatlnfo and FFSetCatlnfo 
calls. 

attrib This field contains attribute flags for an MS-DOS file. These flags are 
$01—a read-only file 

$02—a hidden file (that is, one hidden from normal directory searches) 

$04—a system file (the file is also hidden from normal directory searches) 
$08—an entry that contains the volume label in the first 11 bytes 
$10—an entry that defines a subdirectory (that is, this entry is hidden from 
normal directory searches) 

$20—archive flag: set when the file is written to and closed 
Other bits are reserved. 
filler4 This field is reserved for future use. 
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FFXSetCatlnfo 

The FFXSetCatlnfo call uses the XCInfoPBRec record described below: 

XCInfoPBRec = RECORD 

CInfo : CInfoPBRec; {Input to FFXSetCatlnfo} 

CASE xfs : XFSType OF 
msdos : 

{The following two fields are also used as input to FFXSetCatlnfo} 
(attrib : SIGNEDBYTE; 
filler4 : SIGNEDBYTE) 

END; • 

The case selector for this variable record is defined as follows: 

TYPE 


XFSType = (Mac, ProDOS, MSDOS); 

The fields in this record are used as described below. These fields cannot be changed 
by translators. 

CInfo A pointer to the standard CInfoPBRec record used by the FFGetCatlnfo and 
FFSetCatlnfo calls. 

attrib This field contains attribute flags for an MS-DOS file. These flags are 
$01—a read-only file 

$02—a hidden file (that is, one hidden from normal directory searches) 
$04—a system file (the file is also hidden from normal directory searches) 
$08—an entry that contains the volume label in the first 11 bytes 
$10—an entry that defines a subdirectory (that is, this entry is hidden from 
normal directory searches) 

$20—archive flag: set when the file is written to and closed 
All other bits are reserved. Set these bits to 0. 
filler4 This field is reserved for future use. 
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Appendix A 


Pascal Conventions 
for Translators 


This appendix describes the treatment of different kinds of parameter and function 
results by Macintosh Pascal. It includes descriptions of all the basic Pascal data 
types. 


External calling conventions 

This section describes the treatment of parameters, function results, and register 
conventions. 


Parameters 

Parameters are evaluated from left to right and are pushed onto the stack in that order 
as they are evaluated. The called procedure is responsible for removing the 
parameters from the stack. All VAR parameters are passed as pointers to the actual 
storage location. Note that in cases of byte-wide parameters, the pointer may have 
an odd value. 

Non-VAR parameters are passed in the following ways, depending upon the type of 
the parameter. Values of type Boolean, elements of an enumerated type with fewer 
than 128 elements, and subranges within the range -128..127 are passed as signed 
byte values. (They are pushed as bytes; the MC68000 allocates two bytes for each byte 
on the stack.) The called procedure expects Boolean parameters to be in the range 
0 .. 1 . 

Values of types integer and char and all other enumerations and subranges are 
passed as signed word values. Pascal char values are expected to be in the range 
0..255; the upper half of this range is used for special characters. Pointers and 
longint values are passed as signed 32-bit values. 






Table A-l lists the Pascal parameter passing conventions. 


Table A-l 


Parameter passing conventions 

Parameter type 

Pascal caller... 

Pascal callee... 

Boolean 

Pushes byte: 
range 0-1 

Accesses byte: 
range 0-1 

Enumeration: 
range 0..127 

Pushes byte: 
range 0-127 

Accesses byte: 
range 0..127 

Enumeration: 
range 0-32767 

Pushes word: 
range 0-32767 

Accesses word: 
range 0-32767 

Char 

Pushes word: 
range 0..255 

Accesses word: 
range 0..255 

Subrange: 
range -128.. 127 

Pushes byte: 
range -128-127 

Accesses byte: 
range -128.. 127 

Subrange: 

range -32767-32767 

Pushes word: 
range -32767-32767 

Accesses word: 
range -32767-32767 

Integer 

Pushes word: 
range -32767-32767 

Accesses word: 
range -32767-32767 

Longint 

Pushes long 

Accesses signed long value 

Pointer 

Pushes long 

Accesses long 

Real 

Converts to extended, 
pushes address of 
extended 

Converts extended on stack 
to local real, accesses local 
value 

Double 

Converts to extended, 
pushes address of 
extended 

Converts extended on stack 
to local double, accesses 
local value 

Comp 

Converts to extended, 
pushes address of 
extended 

Converts extended on stack 
to local comp, accesses local 
value 

Extended 

Pushes address of 
extended 

Copies extended to local 
extended, accesses local 
value 

Array, Record, 

String < four bytes 

Pushes value 
(word or long) 

Accesses value (word or long) 

Array, Record, 

String > four bytes 

Pushes address 
of value 

Copies value to local, 
accesses local 

Set 

Pushes set value 
rounded to whole 
number of words 

Accesses value on stack 
(.Note: Use word or long for 
those sizes; accesses 
low-order half of word for 
byte-size set.) 
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Real parameters 

Values of types real, double, comp, and extended are passed as pointers to extended 
values. The Compiler does this in a reentrant way by allocating a temporary location 
in the caller’s activation record, converting the parameter value to an extended value 
in this location and passing a pointer to this location. The called procedure then 
allocates a local location of the declared type and converts the extended value, using 
the pointer, into the location and type. 

Structured parameters 

Arrays, strings, and records whose size is less than or equal to four bytes are passed 
by pushing their value (either a word or a long) onto the stack. Larger arrays, strings, 
and records (as well as extended values, as mentioned above) are passed as a pointer 
to the value; for reentry purposes, the Compiler emits code in the called procedure 
to copy the value to a local storage location. 

Sets are passed by rounding the set size up to the next whole word, if necessary, and 
then pushing the set value so that the lowest-order word is pushed last. In the case of a 
byte-width set, the called procedure will only access the low-order half of the word 
pushed. 


Function results 

Function results are returned by value or by address on the stack. Space for the 
function result is allocated by the caller before the parameters are pushed. The caller 
is responsible for removing the result from the stack after the call. Table A-2 lists the 


conventions for passing each type of function result. 

Table A-2 

Function result passing conventions 


Result type 

Pascal caller... 

Pascal callee... 

After the call 

Boolean 

Allocates 

word 

Returns byte value: 
range 0..1 

Pops byte 

Enumeration: 
range 0..127 

Allocates 

word 

Returns byte value: 
range 0..127 

Pops byte 

Enumeration: 
range 0..32767 

Allocates 

word 

Returns word value: 
range 0..32767 

Pops word 

Char 

Allocates 

word 

Returns word value: 
range 0..255 

Pops word 

Subrange: 
range -128.. 127 

Allocates 

word 

Returns byte value: 
range -128.. 127 

Pops byte 

Subrange: 

range -32768.-32767 

Allocates 

word 

Returns word value: 
range -32768.-32767 

Pops word 

Integer 

Allocates 

word 

Returns word value: 
range -32768.-32767 

Pops word 


(continued) 


External calling conventions 


A-3 



Table A-2 (continued) 

Function result passing conventions 


Result type 

Pascal caller... 

Pascal callee... 

After the call 

Longint 

Allocates 
long word 

Returns long word 
value: range is 
signed 32 bits 

Pops long word 

Real 

Allocates 
long word 

Returns real value 

Pops real value 

Double 

Pushes 
address 
of double 
temporary 

Puts double result 
in temporary 

Pops temporary 
address, accesses 
temporary value 

Comp 

Pushes 
address 
of comp 
temporary 

Puts double result 
in temporary 

Pops temporary 
address, accesses 
temporary value 

Extended 

Pushes 
address of 
extended 
temporary 

Puts extended result 
in temporary 

Pops temporary 
address, accesses 
temporary value 

Array, String, 

Record < four bytes 

Allocates 
word or 
long word 

Returns word 
or long word 

Pops word or 
long word 

Array, String, 

Record > four bytes 

Pushes 
address of 
temporary 

Puts result in 
temporary 

Pops temporary 
address, accesses 
temporary value 

Set: one byte 

Allocates 

word 

Returns byte value 
of result 

Pops byte 

Set: one word 

Allocates 

word 

Returns word value 
of result 

Pops word 

Set: two words 

Allocates 
long word 

Returns long word 
value of result 

Pops long word 

Set > two words 

Pushes address 
of temporary 

Puts result in 
temporary 

Pops temporary 
address, accesses 
temporary value 


Note: Pascal does not assume any initial value for memory space allocated to a function result 
unless it is a pointer to a type that occupies more than four bytes of memory. 
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For types Boolean, char, and integer, and enumerated and subrange types, the 
caller allocates a word on the stack to make space for the function result. Values of 
type Boolean, enumerated types with fewer than 128 elements, and subranges within 
the range -128.. 127 are returned as signed byte values. The value goes in the low- 
address byte, which is the most significant byte of the word. The calling procedure 
expects Boolean results to be in the range 0..1. 

Integer and char values and all enumerated and subrange types not covered above 
are returned as signed word values. Pascal char values are expected to be in the range 
0..255; the upper half of this range is used for special characters. 

For pointers, longint, and the real types, the caller allocates a long on the stack to 
make space for the function result Pointers and longint values are returned as signed 
32-bit values. Values of type real are returned as 32-bit real values. For double, 
comp, and extended types, and for sets, arrays, strings, and records greater than 
four bytes in size, the caller pushes a pointer to a temporary location. 

For one-byte sets and for arrays, strings, and records whose size is one word, the 
caller allocates a word on the stack. For sets, arrays, strings, and records whose size is 
two words, the caller allocates a long word on the stack. One-byte sets are returned as 
a byte value. Sets, arrays, strings, and records whose sizes are one or two words are 
returned as either a word or a long word. 


Register conventions 

Registers DO, Dl, D2, AO, and A1 are considered scratch registers and are not 
preserved across procedure calls. All other registers are preserved by the called 
routine. Register A5 is the global data pointer, register A6 the local frame pointer, 
and register A7 the stack pointer. 
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Appendix B 


Apple File Exchange 
Messages 


The messages listed in this appendix are included in a resource built into Apple File 
Exchange. They are available for use by translators. 


Resource description for Apple File Exchange 
messages 

resource"STR#' (150) { ( 

1**1 

/* General System Errors (VBL Mgr, Queueing, Etc.) */ 

1**1 


/* 

noErr 

EQU 

0 


0 for success */ 

/* 

qErr 

EQU 

-1 

*/ 

"queue element not found during deletion"; 

/* 

VTypErr 

EQU 

-2 

*/ 

"invalid queue element"; 

/* 

corErr 

EQU 

-3 

*/ 

"core routine number out of range"; 

/* 

unimpErr 

EQU 

-A 

*/ 

"unimplemented core routine"; 

/* 

don't know 

EQU 

-5, 

-6 */ 

"unknown problem"; "unsupported function”; 

/* 

format problem 

EQU 

-7 

*/ 

"cannot write directory on this type of disk"; 

/* 

seNoDB 

EQU 

-8 

*/ 

"no debugger installed to handle debugger command' 


1**1 

/* Special for other functions */ 
1**1 


/* EQU -9 */ "total pathname length is too long"; 

1**1 

/* Special for file server */ 

1**1 

/* EQU -10 */ "access denied"; 

/* don't know -11...-16 */ ""; ""; " n ; 

/**/ 
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/* 

I/O System Errors */ 




1**1 





/* 

controlErr 

EQO 

-17 

*/ 

"problem with control call"; 

/* 

statusErr 

EQU 

-18 

*/ 

"problem with status call"; 

/* 

readErr 

EQU 

-19 

*/ 

"problem reading"; 

/* 

writErr 

EQU 

-20 

*/ 

"problem writing"; 

/* 

badUnitErr 

EQU 

-21 

*/ 

"bad unit number used"; 

/* 

unitEmptyErr 

EQU 

-22 

*/ 

"empty unit accessed"; 

/* 

openErr 

EQU 

-23 

*/ 

"problem while opening"; 

/* 

closErr 

EQU 

-24 

*/ 

"problem while closing"; 

/* 

dRemovErr 

EQU 

-25 

*/ 

"tried to remove an open driver"; 

/* 

dlnstErr 

EQU 

-26 

*/ 

"Drvrlnstall couldn't find driver in resources"; 

/* 

abortErr 

EQU 

-27 

*/ 

"10 call aborted by KilllO"; 

/* 

notOpenErr 

EQU 

-28 

*/ 

"driver not opened"; 

/* 

don't know 

EQU 

-29. 

.-32 

*/ .in. na. nn. tin. 

1**1 





/* 

File System error codes */ 


1**1 





r* 

dirFulErr 

EQU 

-33 

*/ 

"Directory is full"; 

/* 

dskFulErr 

EQU 

-34 

*/ 

"disk is full"; 

/* 

nsvErr 

EQU 

-35 

*/ 

"no such volume"; 

/* 

ioErr 

EQU 

-36 

*/ 

"Input/Output error"; 

/* 

bdNamErr 

EQU 

-37 

*/ 

"bad name (possibly too long, bad characters, etc 

/* 

fnOpnErr 

EQU 

-38 

*/ 

"File not open"; 

/* 

eofErr 

EQU 

-39 

*/ 

"End of file"; 

/* 

posErr 

EQU 

-40 

*/ 

"tried to position to before start of file"; 

/* 

mFulErr 

EQU 

-41 

*/ 

"memory full (open) or file won't fit (load)"; 

/* 

tmfoErr 

EQU 

-42 

*/ 

"too many files open"; 

/* 

fnfErr 

EQU 

-43 

*/ 

"File/Folder not found"; 

/* 

wPrErr 

EQU 

-44 

*/ 

"diskette is write protected"; 

/* 

fLckdErr 

EQU 

-45 

*/ 

"file is locked"; 

/* 

vLckdErr 

EQU 

-46 

*/ 

"volume is locked"; 

/* 

fBsyErr 

EQU 

-47 

*/ 

"file is busy (or folder still contains files)"; 

/* 

dupFNErr 

EQU 

-48 

*/ 

"file/folder of that name already exists"; 

/* 

opWrErr 

EQU 

-49 

*/ 

"file already open with write permission"; 

/* 

paramErr 

EQU 

-50 

*/ 

"problem with parameter list sent to file system"; 

/* 

rfNumErr 

EQU 

-51 

*/ 

"file reference number error"; 

B-2 
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/* 

gfpErr 

EQU 

-52 

*/ 

"problem with getting file position"; 

/* 

volOffLinErr 

EQU 

-53 

*/ 

"volume not on line (was Ejected)"; 

/* 

permErr 

EQU 

-54 

*/ 

"permission error; access denied to file/folder"; 

/* 

volOnLinErr 

EQU 

-55 

*/ 

"drive volume already on-line at MountVol"; 

/* 

nsDrvErr 

EQU 

-56 

*/ 

"no such drive (tried to mount a bad drive num)"; 

/* 

noMacDskErr 

EQU 

-57 

*/ 

"not a correct diskette (signature bytes are wrong)"; 

/* 

extFSErr 

EQU 

-58 

*/ 

"volume in question belongs to an external file system"; 

/* 

fsRnErr 

EQU 

-59 

*/ 



"during rename 

the old entry was 

deleted but could not be restored"; 

/* 

badMDBErr 

EQU 

-60 

V 

"bad master directory block"; 

/* 

wrPermErr 

EQU 

-61 

*/ 

"write permissions are incorrect"; 

/* 

unknown 

EQU 

-62,- 

-63 */ 

tin . ttn • 

0 0 

/* 

noDriveErr 

EQU 

-64 

V 

"drive not installed"; 

/* 

offLinErr 

EQU 

-65 

*/ 

"read or write requested for an off-line drive"; 

/* 

noNybErr 

EQU 

-66 

*/ 

"couldn't find disk data in 200 tries - bad disk"; 

/* 

noAdrMkErr 

EQU 

-67 

*/ 

"couldn't find valid address mark on disk — bad disk"; 

/* 

dataVerErr 

EQU 

-68 

V 

"read verify compare failed - disk won't hold its data"; 

/* 

badCkSmErr 

EQU 

-69 

*/ 

"address mark checksum didn't check — disk is going bad"; 

/* 

badBtSlpErr 

EQU 

-70 

*/ 

"bad address mark bit slip nibbles - disk is damaged"; 

/* 

noDtaMkErr 

EQU 

-71 

*/ 

"couldn't find a data mark header — disk is damaged"; 

/* 

badDCkSum 

EQU 

-72 

*/ 

"bad data mark checksum — disk has been damaged"; 

/* 

badDBtSlp 

EQU 

-73 

*/ 

"bad data mark bit slip nibbles - disk is damaged"; 

/* 

wrUnderRun 

EQU 

-74 

V 

"write underrun occurred — disk speed may need adjustment 

/* 

cantStepErr 

EQU 

-75 

*/ 

"step handshake failed — disk drive may need calibration" 

/* 

tkOBadErr 

EQU 

-76 

*/ 



"track 0 detect 

doesn 

't change — 

are you sure there's a disk there?"; 

/* 

initIWMErr 

EQU 

-77 

*/ 



"unable to initialize 

disk 

interface — check cables to disk drive"; 

/* 

twoSideErr 

EQU 

-78 

*r 

"tried to read 2nd side on a 1-sided drive"; 

/* 

spdAdjErr 

EQU 

-79 

*/ 

"unable to correctly adjust disk speed"; 

/* 

seekErr 

EQU 

-80 

*/ 



"unable to seek 

to correct 

track 

on disk — disk may be going bad"; 

/* 

sectNFErr 

EQU 

-81 

*/ 

"sector number never found on a track - disk is going bad 

/* 

fmtlErr 

EQU 

-82 

*/ 

"can't find sector 0 after track format - disk may be bad 

/* 

fmt2Err 

EQU 

-83 

*/ 

"can't get enough sync — cannot format disk"; 

/* 

VerErr 

EQU 

-84 

*/ 

"track failed to verify — disk won't hold data" 


» 
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Appendix C 

An Example 
of a Translator 


On the following pages, you’ll find listings for Macintosh Programming Workshop 
(MPW) files that make up a sample translator. This translator opens up the resource 
fork of a Macintosh file and copies all resources of the type 'STR#' to a text file on any 
of the file systems. You can use these files as the starting point for a new translator. 

The files listed are 

□ Example.p, written in MPW Pascal, which contains the body of the translator 

□ AFETrans.p, which contains Pascal declarations used by Example.p 

□ Example.a, written in 68000 assembly language, which contains the required 
header for the translator 

D Example.r, a resource description file for the resources used by the translator 

□ Example, file 7—which, when run, creates the translator 

o doit, an MPW shell script created by Example, file 7 for assembling, compiling, 
and linking the files 

□ Example.make, the MAKE file used to control the building of the translator 

A disk called ExampleTrans is provided with this manual. It includes the files listed 
above, as well as these additional files: 

□ Example.rsrc, the resource file for the translator 

□ Example Translator, the finished translator 







Example.p 

unit TransExample; 

{* 

* 

★ ~ “ ' ' — ' . 

* File: Example.p 

★ 

* Example translator between Macintosh, ProDOS, and MS-DOS. 

★ 

* 

*} 

{* This translator opens up the resource fork of a Macintosh file and copies * 

* all resources of the type STR# to a text file on any of the file systems. * 

* If the translation is Mac to Mac a dialog box is available to set the * 

* creator type of the text file (to open it just double click on it ). * 

* Note that this dialog box is only available when the translator is in the * 

* Mac to Mac menu, in the other menus it will not appear since Mac creator * 

* types have no meaning in the other file systems. Also notice how this * 

* translator protects itself from being loaded into menus in which it has no * 

* usefulness. *) 

INTERFACE 

USES 

(SLOAD MacLoad.L) MemTypes,QuickDraw,oslntf,toollntf,packIntf,macPrint,script, 

{SLOAD } AFETrans; 

{ AFETrans contains all of the standard AFE data structure definitions } 

{ This is the function through which AFE communicates with the translator } 
function TranStr(Message : integer; VAR TranslateData : Handle; 

Param : longint; Self : handle) : longint; 

IMPLEMENTATION 

{SR-} 

CONST 

{************************************************************************ 

* ★ 

* constants for strings (for error messages) * 

* the order of these strings is the same as in Example.r * 

* ★ 

*********************************************************************** j 

str_error = 1; { "An error occurred while " ) 

str_creating = 2; { "creating the destination file: " ) 

str_opensrc =3; { "opening the source file: " } 

str_opendst =4; { "opening the destination file: " } 

str_getflnfo = 5; { "getting information about the file: " ) 

s tr_setfinfo = 6; { "setting the file type of the destination file: " ) 

str_reading =7; { "reading in the source file: " ) 

str_writing =8; { "writing out the destination file: " ) 

str_copying = 9; { "Copying STR# resources.." } 

str_initing = 10; { "initializing the translator " ) 

str_period = 11; { } 

str_cant = 12; { "It cannot translate from " ) 
str_to =13; { " to " ) 

str_delsrc = 14; { "deleting the original file (your translated data is in the file 
SSSAFE-TEMPSSS): " } 

str_rendst = 15; { "renaming the destination file (your translated data is in the 
file SSSAFE-TEMPSSS): "} 

str_numstrings = 16; { "Number of STR# resources in this file: " } 
str_stringRes =17; ( "String Resource number ” ) 
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{************************************************************************ 

* * 

* constants for dialog box * 

* these are the item numbers for the objects in the options dialog box * 

* * 

********************************************************,**************} 
d_OK = 1; 
d_Cancel = 2; 
d_text =3; 
d_MWradio = 4; 
d_MSWradio = 5; 
d_MPWradio = 6; 
d_MDSradio =7; 
d_otherRadio = 8; 
d_MHicon = 9; 
d_MSWicon = 10; 
d_MPWicon = 11; 
d_MDSicon = 12; 
d_otherText =13; 

{************************************************************************ 

* * 

* Miscellaneous Constants * 

* * 

***********************************************************************j 

tMCMC = 1; { Mac to Mac translation } 
tMCPD = 2; { Mac to ProDOS translation } 
tMCMS = 3; { Mac to MS-DOS translation } 

{************************************************ 

* The following are offsets from the MacWrite * 

* button in the options dialog box * 

************************************************ j 

tMacWrite = 0; { MacWrite } 
tMSWord = 1; { Microsoft Word } 
tMPW = 2; { MPW } 
tMDS = 3; ( MDS 68000 } 
tother =4; { other ) 

{************************************************ 

* The following are creator names for the apps * 

* in the options dialog box * 

************************************************j 

fMacWrite = 'MACA'; { MacWrite > 
fMSWord = ' MWRD' ; { Microsoft Word } 
fMPW = 'MPS '; { MPW ) 
fMDS = 'EDIT 1 ; { MDS 68000 } 

fromFS = 0; { denotes the source file system } 
toFS = 1; { denotes the destination file system } 

TXPE 

{This data type is used to hold the File system nicknames, MC,MS,PD. } 
halfResType = packed array[1.. 2] of char; 

{*************** G]_ 0 bal Variables record **************} 

StatusRec = RECORD 

mystatus : longint; { keeps the status bits for the translator, 
see discussion about TranData in the manual } 
mylD : integer; { ID number of the STR# resource containing 
error strings ) 

myfref : integer; { The file reference number for my resource file } 
trankind : integer; { The type of translation occurring, eg Mac to Mac} 
ftype : OSType; { The creator name for the destination file } 
fkind : integer; { the offset from the MacWrite dialog button } 
frHandle ; Handle; { handle to the source file system resource } 
toHandle : Handle; { handle to the destination file system ) 
srcsize : longint; { byte size of the source file } 
end; 

StatPtr = A StatusRec; 

StatHndl = ''StatPtr; 




( Listing of all the functions in this unit ) 

Function Activate(statRec : statHndl; trnPB : trnPtr) : longint; Forward; 

Function CopyFile <srcref,dstref : integer; statRec : statHndl; trnPB : tmPtr) 

: OSErr; Forward; 

Function DoAppear(trnpb : trnptr; statRec : statHndl) : longint; Forward; 

Function DoFileConvert(statRec : statHndl; trnPB : trnPtr) : longint; Forward; 
Function DoFinish(VAR translateData : handle) : OSErr; Forward; 

Function Dolnit(VAR translateData,self : handle; trnpb : trnPtr) 

: longint; Forward; 

Function DoName(statRec ; statHndl; trnPB : trnPtr) : longint; Forward; 

Function FileIO(ff,fs : integer; pb : HParmBlkPtr; statrec : StatHndl; tmPB : tmPtr) 
: OSErr; Forward; 

Function FileOp(ff,fs : integer; pb : HParmBlkPtr; statrec : StatHndl; trnPB : tmPtr) 
: OSErr; Forward; 

Function GetStrSize(fref : integer) : longint; Forward; 

Function RecogFile(statRec : statHndl; tmPB : tmPtr) : longint; Forward; 

Procedure ReportErr(err,doing : integer; statRec : statHndl; tmPB ; tmPtr); Forward; 


{*************************** Activate ************************************** 

* Called when translator receives a tm_Activate. * 

* ACTIVATE indicates that the user wishes to check this menu item. The * 

* routine does whatever it wants (usually just setting the appropriate bit * 

* in the flags, but it could be as complicated as a dialog box prompting * 

* the user for options), and then returns the new status flag as the * 

* function result. In this case Activate only puts up a dialog box if it is * 


* being activated in the Mac to Mac menu; otherwise it just updates the * 

* active bit in the status variable. * 

* Notice how the dialog box is only activated for the Mac to Mac trans- * 

* lation. For the other translation the we just set the active bit. * 


***************************************************************************1 
Function Activate (statRec : statHndl; trnPB : tmPtr) : longint; 
var 

user_ptr : dialogPtr; 
cHndl : Controlhandle; 

itype ; integer; { type of item in the dialog box,see Inside Mac 
vol I for details) 

iHndl : handle; { a handle to an item } 

irect : rect; ( the display rectangle for the item ) 

i : integer; 

str : str255; 

item : integer; 

curfkind : integer; { the current destination file type ) 
oldres : integer; 
begin 

( if the translation is to prodos or msdos } 
if statrec''*.tranKind > tMCMC 

then statRec**.mystatus := bor (tmActive, statRec**.mystatus) 
else if statrec**.tranKind = tMCMC then begin 

{ if the translation is Mac to Mac than get the option dialog box } 
oldres := curResFile; { in case another resource file is being used ) 
useResFile(statRec**.myFref); 

userjptr := getNewDialog(statRec**.myID,nil,POINTER(-l) ); 
useResFile(oldres); { restore the old res file } 

{ set up the file type ) 
str := 1 ■; 

( check that the file type only consists of printable ascii characters } 
for i := 1 to 4 do begin 

if statRec**.ftype[i] in [• ’ 

then str[i] := statRec**.ftype[i]; 
end; 

getDItem(user_ptr,d_otherText,itype,iHndl,iRect); 
setIText (iHndl,str); 
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{ set up the radio button } 

( get the previously selected file type, this is an offset from MacWrite) 
curfkind := statrec AA .fkind; 

{ get a handle to that item } 

getDItem(user_ptr,d_MWradio+curfkind,itype, iHndl, iRect); 
cHndl := POINTER(iHndl) ; 

{ turn the button to that item on ) 

SetCtlValue(cHndl,1); 

{ display the dialog box on the screen ) 
showWindow (user_ptr); 

repeat- 

{ wait for a click in the dialog box } 
modalDialog(NIL, item) ; 

( if click anywhere except OK or Cancel } 
if item in [d_MWradio..d_otherText] then begin 

{ if clicked on document icon calculate to which radio button } 

{ it belongs. ) 

if item >= d_MWicon then item := d_MWradio + (item - d_MWicon); 

{ if the new choice is not the same as the old choice ) 
if curfkind <> (item - d_MWradio) then begin 
{ get a handle to the old item ) 

getDItem(user_ptr,d_MWradio+curfkind,itype,iHndl,iRect); 
cHndl := POINTER(iHndl); 

{ turn its radio button off } 

SetCtlValue(cHndl, 0); 

( get a handle to the new item } 
getDItem(user_ptr,item,itype,iHndl,iRect); 
cHndl := POINTER(iHndl); 

{ turn its radio button on } 

SetCtlValue(cHndl, 1); 

{ calculate the new offset from MacWrite ) 
curfkind :=» item - d_MWradio; 

( if the Other radio button is not highlighted then put ) 

{ the apporiate creator type in the text box } 
if curfkind < tother then begin 
case curfKind of 

tMacWrite : str :=* fMacWrite; 
tMSWord : str := fMSWord; 
tMPW : str :=■ fMPW; 
tMJS : str := fMDS; 
end; 

getDItem (user_ptr,d_otherText,itype,iHndl,iRect); 

SetIText(iHndl,str); 
end; 
end; 
end; 

until item in [d_OK,d_Cancel]; 
if item =» d_OK then begin 

{ save the destination file type in the Global variable } 
statrec AA .fkind := curfKind; 

getDItem(user_ptr,d_otherText,itype,iHndl,iRect); 

GetIText(iHndl,str); 

{ Make sure that the file type is four characters long } 
statrec AA .ftype := 1 1 ; 

{ Take only the first four characters of the file type ) 
for i := 1 to 4 do begin 
if length (str) >= i 

then statrec AA .ftype[i] := str[i]; 
end; 

{ Set the Active bit in the status variable } 

statRec AA .myStatus := bor(statRec AA .myStatus,trnActive); 

end; 

DisposDialog(user_ptr); 
end; 

{ Return the current translator status. ) 

Activate := statRec AA .myStatus; 
end; { Activate } 
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{* This is the function that actually does the translation of the STR# re- * 

* source to a text file. 

INPUT : srcref,dstref - file reference numbers for the source and destination 
file. 

datasize - the size of the source file 
statRec - the Global variable record. 

RESULT: The sucess or failure of the translation. 

USED by : DoFileConvert 

* Notice its use of tprocs to transliterate between the various character 

* sets used by the different file systems. Also notice that whenever tprocs 

* are called we make sure it is loaded in memory by using LoadResource, just 

* because we have a handle to it does not mean it resides currently in 

* memory because it is a purgeable resource. 

*} 

Function CopyFile (srcref,dstref : integer; statRec : statHndl; tmPB : tmPtr) : OSErr 
var 

oldres : integer; 

numstr,numentries : integer; 

s,n : integer; 

hstr : handle; 

numptr : ^integer; 

str : str255; 

thelD : integer; 

theType : ResType; 

theName : str255; 

datasize : longint; 

buf : arrayfO..511] of signedbyte; 

bufsize : integer; 

pb : ParamBlockRec; 

tpb : transPB; 

tproc : hdrHndl; 

{* This procedure finds the desired TProc for the transliteration 
* between the Mac and one of the other file systems and intializes it 
*) 

Procedure GetTProc; 
var 

tp : tprfHndl; 
found : boolean; 
entry : integer; 
i : integer; 

loCharSet,hiCharSet : integer; 
theverb : integer; 
theflag : integer; 
err : OSErr; 
begin 

tproc := NIL; 

{ One doesn't need a Tproc if the translation involves only one 
computer type ) 

if statrec A/ ' .trankind = tMCMC then exit (GetTProc) ; 

{ get a handle to the Tproc family for the given source country, 
if more than one trpf is available the user chooses which one to 
use from the country menu provided by AFE. } 
tp : = POINTER (getResource ( 1 tprf 1 , trnpb A . t mcountry)) ; 
if tp = NIL then exit(GetTProc); 
case statrec''". tranKind of 
tMCPD : begin 

loCharSet := cfMacintosh; 
hiCharSet := cfASCII; 
theverb := transLotoHi; 
theflag := trNonOnetoOne; 
end; 

tMCMS : begin 

loCharSet := cfMacintosh; 
hiCharSet := cflBMPC; 
theverb := transLotoHi; 
theflag := trNonOnetoOne; 
end; 
end; 
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found := false; 

{ Search through the whole tproc family for the one that translates 
between the two character families } 
for i := 1 to tp**.lastentry do with tp**.tprocs[i] do begin 
if altcountry = trnpb* .tmcountry then 

if (curCharFam = loCharSet) and (altCharFam = hiCharSet) then begin 
found := true; 
entry := i; 
leave; 
end; 

end; 

if not found then exit (GetTProc); 

( Get a handle to the tproc specified by the tproc family entry } 
tproc := POINTER (GetResource('tprc',tp**.tprocs[entry] .tprcID)) ; 

{ exit if the resource cannot be found } 
if tproc = NIL then exit(GetTProc); 

{ if not currently in memory thant load it now } 
if tproc 1 ' = NIL then loadResource (POINTER (tproc) ) ; 
with tpb do begin 

feature flags := band (tproc* 1 '. flags, theflag) ; 
newcntry := -1; 

{ these fields are reserved set to zero ) 

tpRsrv[0] := 0; 

tpRsrv[l] := 0; 

tpRsrv[2] := 0; 

tpRsrv[3] := 0; 

{ initialize transliteration procedure ) 
verb := translnit; 
err := CallTProc(tpb,tproc); 
if err <> noerr then begin 
tproc := NIL; 
exit (GetTProc) ; 
end; 

{ the translations will be transLotoHigh } 
verb := theverb; 
end; 
end; 


{* This procedure send the source string to the Transliteration 

* procedure and returns the result in tpb.dstText.trPtr. The verb for 

* the translation was set in GetTProc. 

* OUTPUT : Bufsize is changed to be the size of the destination 

* buffer. It is used in WriteString. 

*> 

Procedure TranslitString(VflR str : str255); 
var 

err : OSErr; 
begin 

{ if there is no tproc than just move the source buffer to the 
ioBuffer buf fer ) 
if tProc = NIL then begin 

blockmove(POINTER(ORD4(@str)+1),@buf,length(str)); 

bufsize := length(str); 

end 

else begin 

tpb.srcText.trLen := length(str); 

( The first element of a string is its size, since we do not 
want to translate this character we set the buffer to the 
next one. } 

tpb.srcText.trPtr := POINTER(ORD4 (@str)+1) ; 
tpb.srcText.trFont := 0; 
tpb.dstText.trLen := 512; 
tpb.dstText.trPtr := @buf; 
tpb.dstText.trFont ;= 0; 

(if the tproc is not in memory than load it ) 
if tproc* = NIL then loadResource(POINTER(tproc)); 
err := CallTProc(tpb,tProc); 
bufsize := tpb.dstText .trLen; 
end; 
end; 
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{* This procedure writes out a string to the destination file and adds 

* a carriage return if cr is true. It assumes that the string is 

* already pointed to by pb.ioBuffer using the assignment 

* pb.ioBuffer := @Buf. It also assumes that GetTProc has already been 

* called to get the required TProc. 

*} 

Procedure WriteString(str : str255; cr : boolean); 
var 

pet : integer; 
err : OSErr; 
begin 

{ Use the tprocs to transliterate between character sets } 

TranslitString(str) ; 

pb.ioReqCount := bufsize; 

err := FilelO (FFWrite, tofs, 8pb, statrec, tmpb) ; 

{ add the carriage return to the destination file } 
if cr and (err = noerr) then begin 
buf[0] := 13; (carriage return} 
bufsize := 1; 

{ if translating to an MSDOS disk a line feed is also needed to 
start a new line. } 

if statrec / ' / '.tranKind = tMCMS then begin 
buf[l] := 10; { line feed } 
bufsize := 2; 
end; 

pb.ioReqCount := bufsize; 

err := FilelO (FFWrite, tofs, @pb, statrec, tmpb) ; 
end; 

{ report any error that occurred while writing to the destination } 
if err <> noerr then begin 

reporterr(err,str_writing,statrec,trnpb); 

CopyFile :=> err; 
useResFile(oldres); 
exit(copyFile) 
end; 

{ compute how much of the translation has been completed for 
display in the status window } 
datasize := datasize+length(str); 
pet := datasize * 100 div statrec''''.srcSize; 
if pet < 0 then pet :=■ 0 
else if pet > 100 then pet := 100; 

{ if user clicks on cancel } 

if not CallStatf",pet, 1,tmpb''.trnStatProc) then begin 
CopyFile := tmCancel; 
useResFile(oldres); 
exit(copyFile); 
end; 
end; 

{* This procedure writes out the first line of the destination file 
* it tells how many strings there are to translate } 

Procedure Header(numstr : integer); 
var 

oldres ; integer; 
str : str255; 
begin 

datasize := 0; 

GetTProc; 

pb.ioCompletion := NIL; 
pb.ioRefNum := dstref; 
pb.ioBuffer := @buf; 
pb.ioPosMode := fsAtMark; 
oldres := CurResFile; 
useResFile (statRec AA .myfref) ; 

GetlndString(str,statrec AA .myID,str_numstrings); 

WriteString(str,false); 

{ convert the count of STR# resources to a string } 

NumToString(numstr,str); 

WriteString(str,true); 
useResFile(oldres); 
end; 
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{* This procedure writes to the destination file a line stating the 
* string resource ID number 
*} 

Procedure Headerstring(s,thelD,numentries : integer; theName : str255) 
var 

oldres : integer; 
str : str255; 
begin 

oldres := CurResFile; 
useResFile(statRec AA .myfref); 

{ Insert a blank line } 

WriteString(' 1 ,true); 

{ Write the string 'String Resource Number * } 

GetIndString(str,statrec AA .myID,str_stringRes); 

WriteString(str,false); 

{ convert the resource ID number to a string } 

NumToString (thelD,str); 

WriteString(str,true); 

{ make the old resource the current one } 

useResFile(oldres); 

end; 


{* This procedure writes to the destination file one of the strings in 
* a STR# resource. It is called from the main body of CopyFile 
*} 

Procedure EntryString(str : str255; n : integer); 
var 

oldres : integer; 
str2 : str255; 
begin 

WriteString(str,true); 
end; 

begin { Main body of CopyFile } 

{ save the current resource file to restore later } 
oldres := CurResFile; 
useResFile(srcref) ; 

{ get the number of STR# resources ) 
numstr :« countlResources('STR#'); 

{ Write the number of STR# resources to the destination file. ) 

Header(numstr); 

for s :» 1 to numstr do begin 

{ get the sth resource from the source file ) 
hstr :=» GetlIndResource('STR#',s); 
if hstr = NIL then leave; 

GetResInfo(hstr,thelD,theType,theName); 

{ make numptr point to the same place as the master pointer 
of the STR# resource. Since numptr is of a different type we 
use Pointer to avoid type conflicts. } 
numptr := POINTER (hstr A ) ; 

{ The first value in a STR# resource is the number of strings in 
the resource (an integer value). Since numptr is a A integer, it 
is pointing to this value } 
numentries := numptr A ; 

Headerstring(s,thelD,numentries, theName); 

( get each string in the resource and write it to the destination 
file ) 

for n := 1 to numentries do begin 
GetIndString(str,theID,n); 

Entrystring (str, n) ; 
end; 
end; 

{ if we have been using a tproc tell it that we have finished the 
translation > 

if tproc <> NIL then begin 
tpb.verb := transdone; 

if tproc A = NIL then loadresource(POINTER(tproc)); 

if CallTProc(tpb,tproc) <> noerr then ; 

end; 

useResFile (oldres); 

CopyFile := noerr; 
end; ( CopyFile ) 



{******************************* DoAppear ******************************* 

* DoAppear is called in response to a tm_APPEAR message which occurs when * 

* a new disk has been selected which has caused this routine to appear in * 

* its menu. We do not change appearance in the menu, except to clear any * 


* '3 ra y bits that may have been set. Returns NoErr as function result. * 

* Some functions may use this procedureto define some global data- * 

* (such as source or destination FS, etc ). * 

* Notice how the grey bit is turned off. First we create this bit value * 

* with all the bits except for the grey bit on (-1 = $FFFFFFFF) Then we * 

* bit and this with the current status, any high bits in the current * 

* status remain high and none that are not are activated. This is called * 


* masking, and is the most effecient method for changing individual status * 

* bits. * 

**★***★*★★***★***★****************************************************.***** y 

Function DoAppear (tmpb : tmptr; statRec : statHndl) : longint; 
begin 

statRec*'' .myStatus := band (statRec** .myStatus, -1-tmGray) ; 

DoAppear := noErr; 
end; { DoAppear } 

{********************************** DoFileConvert *************************** 


* Called when the translator receives a tm_FILE. Result = Accept,unAccept, * 

* or Cancel. * 

* This function creates the necessary files for the translation to occur. * 

* The actual translation is done by another function CopyFile. * 

* Notice the care used in regards to duplicate file names, particularly the * 

* creation of an intermediate file when copying in place (ie replacing the * 

* source with the destination file). * 


*************************************,*,*,*,*****,**„,****,**,*»*****,,***»,j 

Function DoFileConvert(statRec : statHndl; trnPB : trnPtr) ; longint; 
var 

err,err2 : OSErr; 

srcopened,dstcreated,dstopened,tempfile ; boolean; 
pb ; HParamBlockRec; 
pbold,pbnew : WDPBRec; 
catpb : CInfoPBRec; 
srcref,dstref : integer; 
frstr,tostr : str255; 
str : str255; 
begin 

DoFileConvert := unaccept; 

( Note how we always use the same recognize for trn_File and trn_Recognize 
if RecogFile(statRec,trnPB) = accept then begin 
DoFileConvert := accept; 
srcopened := false; 
dstcreated := false; 
dstopened := false; 
tempfile := false; 

tostr := tmPB A .tmnames'"'.names[l]; ( source file name ) 
frstr := trnPB A .trnnames AA .names[0]; { destination file name } 
err := noerr; 

{ create the destination file ) 
if err = noerr then with pb do begin 
ioNamePtr := Stostr; 
pb.ioFVersNum := 0; 

err := FileOp(FFCreate,toFS,@pb,statrec,trnpb); 

{ if the file already exists ) 
if err = dupfNErr then begin 

{ check to see if it is the source file ) 
if (trnpb A .tmfrID = tmpb A .tmtoID) 

and (tmpb A .tmfrVRef = tmpb A .tmtoVRef) 
and (tmpb A .tmfrpar = tmpb A .tmtopar) 
and (tostr = frstr) then begin 
{ if it is then create a temporary file to hold the tran¬ 
slation ) 

tostr := ■$$$@FE-TEMP$$$ 1 ; 
repeat 

{ increment the fourth letter by one until we get } 

( a unique name for the temporary file ) 
tostr [4] ;= CHR (ORD (tostr [4]) +1) ; 
err := FileOp (FFCreate, toFS, @pb, statrec, tmpb) ; 
until err <> dupfNErr; 
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{ if another error occurred then do not translate } 
if err <> noerr then err := fBsyErr 
else tempfile := true; 
end 

{ if the destination is not the same as the source then delete 
the current file and create a new destination file } 
else begin 

ioNamePtr := @tostr; 
ioFVersNum := 0; 

err2 := FileOp(FFDelete,toFS,@pb,statrec,trnpb); 
if err2 = noerr then begin 
ioNamePtr := @tostr; 
pb.ioFVersNum := 0; 

err := FileOp(FFCreate,toFS,@pb,statrec,trnpb); 
end; 
end; 
end; 

( if the last operation was successful then the destination file 
was created } 
if err = noerr 

then dstcreated := true 

else reportErr(err,str_creating,statRec,trnPB); 
end; 

( if a Mac to Mac translation } 
if statRec**.trankind = tMCMC then begin 
{* Note: before doing a SetFInfo it is a good idea make sure that there is 
* valid information in all param block fields so do a GetFInfo first 
if err = noerr then with catpb do begin 
ioNamePtr := Stostr; 
ioFDirlndex := 0; 

err := FileOp(FFGetFInfo,toFS,@catpb, statrec,trnpb); 

{ If the destination gives a bad param block try the source } 
if err <> noerr then begin 
ioNamePtr :=■ @frStr; 
ioFVersNum := 0; 

err :=> FileOp (FFGetFInfo, fromFS, Scatpb, statrec, trnpb) ; 
err := noerr; 
end; 
end; 

{ Set the destination file type and creator ) 
if err = noerr then with catpb do begin 
ioNamePtr := @tostr; 
loflFndrlnfo.fdtype := 'TEXT'; 
ioflFndrlnfo.fdcreator := statrec**.ftype; 
err FileOp(FFSetFInfo,toFS,Scatpb, statrec,trnpb); 
if err <> noerr then reportErr(err,str_setfinfo,statRec,trnPB); 
err := noerr; 
end; 
end; 

{ For all file systems open the destination } 
if err = noerr then with pb do begin 
ioNamePtr := Stostr; 
if statrec**.tranKind = tMCPD 
then ioPermssn := 0 
else ioPermssn := fsWrPerm; 
ioMisc := NIL; 

err := FileOp(FFOpen,toFS,@pb,statrec,trnpb); 
if err = noerr then begin 
dstopened := true; 
dstref := ioRefNum; 
end 

else reportErr (err, str_opendst, statRec, tmPB) ; 
end; 

{ check to see if the file is already opened } 
if err = noerr then with catpb do begin 
ioNamePtr := Sfrstr; 
ioFVersNum := 0; 
ioFDirlndex := 0; 

err := * FileOp (FFGetFInfo, fromFS, @catpb, statrec, trnpb); 

if err <> noerr then reportErr (err,str_getfinfo,statRec,trnPB); 

end; 



if (err = noerr) and (band(catpb.ioFlAttrib,$04) = 0) then with pb do begin 
pbold.ioCompletion := NIL; 
pbold.ioNamePtr := NIL; 
err := PBHGetVol(Spbold,false); 
if err = noerr then with pbnew do begin 
ioCompletion := NIL; 
ioNamePtr := NIL; 
ioVRefNum := tmpb A .tmfrvref; 
ioWDDirlD := tmpb A . trnfrpar; 
err := PBHSetVol(Spbnew,false); 
end; 

if err = noerr then begin 

srcref := OpenResFile (tmpb A .trnNames AA .names [0]) ; 

err := PBHSetVol<@pbold,false); 

end; 

{ if the resource fork of the source could not be opened then exit } 
if (err = noerr) and (srcref <= 0) then err := fnferr; 
if err = noerr then begin 
srcopened := true; 
end 

else reportErr (err, str_opendst, statRec, tmPB) ; 
end 

else if err = noerr then srcRef := catpb.ioFRefNum; 

( If opened destination get size of source strings, this value is saved in 
statrec AA .srcsize after opening the source file *} 
if err =* noerr then with catpb do begin 
statrec AA .srcsize := GetStrSize (srcref) ; 
end; 

( If no errors so far then translate the file } 

GetlndString(str,statrec AA .mylD, str_copying) ; 

if not CallStat (str, 0,1, tmpb A .trnStatProc) then err := trnCancel; 
if err = noerr then err := copyFile (srcref, dstref, statrec, tmpb) ; 
if not CallStatC ',100,1,trnpb A .trnStatProc) then err := trnCancel; 

{ Close the files and erase any temporary files } 
if srcopened then with pb do begin 
CloseResFile (srcref) ; 
end; 

if dstopened then with pb do begin 
ioRefNum := dstref; 

err2 := FilelO(FFClose,tofs,@pb,statrec,trnpb); 
end; 

{ If an error occurred during translation than delete the destination 
file, it is not valid ) 

if (err <> noerr) and dstcreated then with pb do begin 
ioNamePtr := @tostr; 
ioFVersNum := 0; 

e tr2 := FileOp(FFDelete,toFS,@pb,statrec, trnpb); 
end; 

( if a translation in place was completed then delete the source and 
rename the destination with the source name ) 
if (err = noerr) and tempfile then with pb do begin 
ioNamePtr := Sfrstr; 
ioFVersNum := 0; 

err 2 := FileOp(FFDelete,toFS,@pb,statrec,trnpb); 
if err2 o noerr then reportErr(err2,str_delsrc,statRec,trnPB); 
if err2 = noerr then begin 
ioNamePtr := @tostr; 
ioFVersNum := 0; 
ioMisc := @frstr; 

err2 := FileOp(FFRename,toFS,@pb,statrec,trnpb); 
if err2 <> noerr then reportErr(err2,str_rendst,statRec,trnPB); 
end; 
end; 

if err = trncancel then DoFileConvert := trnCancel; 
end; 

end; { DoFileConvert } 
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{************************************** Dopinish **************************** 


* Called when transltor receives an trn_FINIS. * 

* DoFinish cleans up any global variables that might have been allocated. * 

* ALWAYS returns NoErr. It is only called when execution of AFE is * 

* terminated (ie. you hit quit ). * 


*****************************************************************,*,******„ j 

Function DoFinish(VAR translateData : handle) : OSErr; 
begin 

DoFinish := noErr; 

if translateData <> NIL then disposHandle(translateData); 

translateData := NIL; 

end; 

{************************************** Doinit ****************************** 

* Called whenever a translator receives a trn_INIT message. This happens * 

* when translators are imported to other menus as well as at startup. * 

* Dolnit initializes the variables we need. It allocates a relocatable * 

* block of memory and puts the handle in translateData. It determines the * 

* source and dest file system and sets up the default parameters. It * 

* returns noErr if all goes well, and a negative result otherwise. * 

**********************************************************************„*** j 

Function Dolnit(VAR translateData,self : handle; trnpb : trnPtr) : longint; 
var 

thelD ; integer; theType : restype; namefr,nameto, myname : str255; 
str : str255; 

dstnick,srcnick : halfResType; 
err : OSErr; 
statRec : StatHndl; 
kind : integer; 
srcHandle,dstHandle ; handle; 
len : integer; 
thefref : integer; 
begin 

(* get handles of source and dest file systems 

* Note; GetResource returns NoErr even if it does not find the 

* resource. This is why one must check for NIL handles as well as 

* ResError.} 

srcHandle := GetResource(foreignFS,trnpb''.tmfrID) ; 
err := ResError; 

if (err » noErr) and (srcHandle = NIL) then err := resNotFound; 
if err = noerr then begin 

dstHandle :« GetResource (foreignFS, tmpb A .trntoID) ; 
err :=* ResError; 

if (err = noErr) and (dstHandle = NIL) then err := resNotFound; 
end; 

{* get nickname of source file system = The last two characters of 

* the file system name; MC, MS, PD. } 
if err = noerr then begin 

GetResInfo (srcHandle, thelD, theType, namefr); 

err :*■ ResError; 

end; 

if err = noErr then begin 
len := length (namefr) ; 
if len <= 2 then err := bdNamErr; 
end; 

if err = noErr then begin 

srcnick[l] := namefr[len-1]; srcnick[2] := namefr[len]; 
if (srcnick <> ’PD') and (srcnick <> 'MS') and (srcnick <> 'MC') 
then err := extFSErr; 
end; 

{* get nickname of destination file system *} 
if err = noerr then begin 

GetResInfo (dstHandle, thelD, theType, nameto); 

err := ResError; 

end; 

if err = noErr then begin 
len := length(nameto); 
if len <= 2 then err := bdNamErr; 
end; 



if err = noErr then begin 

dstnick[l] := nameto[len-l]; dstnick[2] := nameto[len]; 
if (dstnick <> 'PD') and (dstnick o 'MS') and (dstnick o 'MC') 
then err := extFSErr; 
end; 

{* get information about translator. Keeping the file reference number 

* allows one to switch the resource file in use to one's own if it is 

* not the current one. 

*} 

if err = noerr then begin 

getResInfo(self,thelD,thetype.myname); 

err := ResError; 

end; 

if err = noerr then begin 

theFRef := homeResFIle(self); 

err ;= ResError; 

end; 


{* determine kind of translation. This translator only supports tran- 

* slation from the Macintosh file system. If we are not in one of these 

* menus then generate an error. 

*> 

if err = noErr then begin 

if (srcnick='MI') and (dstnick = 'MC') then kind := tMCMC 

else if (srcnick='MC') and (dstnick = 'PD') then kind := tMCPD 

else if (srcnick='MC') and (dstnick = 'MS') then kind := tMCMS 

else err := extFSerr; 
end; 


{* get global data space. Why do we make statrec a pointer to handle can 
you even do this?!? *} 
if err = noErr then begin 

translateData := NewHandle(sizeof(statusRec)); 
statrec := POINTER(translateData); . 
err :=* MemError; 
end; 


{* set up default settings *} 

if err = noErr then with statRec AA do begin 

( Check menu item (make it active) and set the About bit ) 
myStatus :=■ tmActive + tmAbout; 

{ the ID number of the translator resource ) 
myID := theID; 

( the file reference number of the translator file } 
myFref := theFref; 

{ the type of translation (Mac to Mac, etc.) ) 
trankind := kind; 

{ default file type is MacWrite } 
ftype := 'MACA'; 

{ default translation is into a MacWrite file } 
fkind := tMacWrite; 

( Handles to the source and destination file system (resources). ) 
frHandle := srcHandle; 
toHandle := dstHandle; 
end; 
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if err <> noerr then begin 

GetlndString(str,thelD,str_error); 

CallErrLog (str, false, false, tmpb A .tmlogproc) ; 

GetlndString(str,thelD,str_initing); 

CallLog(str, false, false, tmPB A .tmlogproc) ; 

CallLog(myname, false, false, tmPB A .tmlogproc) ; 

GetlndString(str,thelD,str_period); 

CallLog (str, true, false, tmPB A . tmlogproc) ; 

{ If translator is not in a valid menu ) 
if err = extFSerr then begin 

GetlndString(str,thelD, str_cant) ; 

CallLog (str, false, false, tmPB A . tmlogproc) ; 

CallLog (copy (namefr. 1, length (namefr)-2), false, false, trnPB A .tmlogproc) ; 
GetlndString(str,thelD,str_to); 

CallLog (str, false, false, tmPB A . tmlogproc) ; 

CallLog (copy (nameto, 1, length (nameto) -2), false, false, trnPB A .tmlogproc) ; 
GetlndString (str, thelD, str_j3eriod) ; 

CallLog (str, true, false, trnPB A .tmlogproc) ; 
end; 
end; 


Dolnit := err; 
end; ( Dolnit ) 


(******************************* DoName ******************************** 


* Called when the translator receives a tm NEWNAME message * 

* tm_NEWNAME is passed a trnPTR in PARAM. It should check the file * 

* specified as the source and return either NOERR or UNACCEPT as the * 

* function result, depending on whether the file matches the criteria for * 

* acceptance by this routine (it can skip checking for acceptance if the * 

* tmTESTED field is true — in that case, the tmACCEPTED field indicates * 

* whether this file was previously accepted). If acceptable, then * 

* tm_NEWNAME should return a suggested new name for the destination file, * 


* and set the field trnNAMES.NAMECNT to 1. On those occasions when more * 

* than one destination file will be produced, the name handle should be * 

* expanded and trnNAMES.NAMECNT should be increased appropriately. * 

Function DoName (statRec : statHndl; tmPB ; tmPtr) : longint; 


var 


temp : longint; 
pb : HParamBlockRec; 
err : OSErr; 
str : str255; 

begin 

DoName := unaccept; 

if RecogFile (statRec, tmPB) = accept then begin 
str := tmpb A .tmNames AA .names [0] ; 
tmpb A .trnNames AA .NameCnt := 1; 
pb.ioNamePtr := @str; 
pb.ioDirlD := trnpb A .trnToPar; 
pb.ioVRefNum := tmPb A .trnToVRef; 

err := FileOp (FFMakeFName, toFS, @pb, statrec, tmpb) ; 
if err = noerr then begin 

trnpb A .tmNames AA .names [1] := str; 

DoName := accept; 
end; 
end; 

end; { DoName ) 


Example.p 
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I ******************************** FilelO ********************************* 


* Called by CopyFile, DoFileConvert * 

* This is a utility function that does the repetitive actions for * 

* FFREAD, FFWRITE, and FFCLOSE. The Calling procedure provides: * 

* ioRefNum * 

* ioposModet, ioposOffsett * 

* ioReqCountt, ioBuffer t * 

* * 

* t for READ and WRITE only * 

* _ 


*****************************************************************„*********j 

Function FileIO(ff,fs : integer; pb : HParmBlkPtr; statrec : StatHndl; 
trnPB : tmPtr) : OSErr; 

var 

err : OSErr; 
begin 

pb''. ioComp let ion := NIL; 
err := noErr; 
if fs = fromFS 

then err := CallFS (ff, tmpb*.trnfrData, POINTER (pb) , false, statrec**. frHandle) 
else err := CallFS (ff, trnpb' .tmtoData,POINTER (pb) , false, statrec-'''.toHandle) ; 
FilelO :=> err; 
end; { FilelO } 

{******************************** FileOp ********************************* 


* Called by DoFileConvert, DoFileName, RecogFile * 

* for FFOPEN, FFGETFINFO, FFGETCATINFO, FFSETCATINFO, FFSETFINFO, FFRENAME,* 

* FFDELETE, FFCREATE, FFGETXCATINFO, FFSETXCATINFO, FFMAKEFNAME * 

* Calling procedure provides (in the pb variable): * 

* ioMisc,ioPermssn,ioNamePtr — FFOPEN * 

* This function provides the part of the CallFS function that does not * 

* change for the calls listed above. It eliminates having to repeat it for * 

* every one of the calls. * 


*»**»*»»****,***,**********************************************************^ 

Function FileOp(ff,fs : integer; pb : HParmBlkPtr; statrec : StatHndl; trnPB : trnPtr) 
{ ff = file system command, fs = source or destination file } 
var 

err : OSErr; 
begin 

with pb* do begin 

ioConpletion := NIL; 
if fs = fromFS then begin 

ioVRefNum := tmpb*.tmfrVRef; 
ioDirlD := trnpb-'.tmfrPar; 

err := CallFS (ff, tmpb-'.trnfrData, POINTER (pb), false, statrec**.frHandle) ; 
end 

else begin ( perfrom operation on the source file ) 
ioVRefNum := tmpb*.tmtoVRef; 
ioDirlD := trnpb*.tmtoPar; 

err := CallFS (ff, tmpb* .tmtoData, POINTER (pb), false, statrec**. toHandle) ; 
end; 
end; 

FileOp := err; 
end; { FileOp } 

Function GetStrSize(fref : integer) : longint; 
var 

oldres : integer; 
size : longint; 
h : handle; 
numstr, s : integer; 
begin 

oldres := curResFile; 

useResFile(fref) ; 

setResload(false); 

numstr := countlResources( 1 STR# 1 ); 

size := 0; 

for s := 1 to numstr do begin 
h := GetllndResource('STR#',s); 
size := size + MaxSizeRsrc(h); 
end; 

setResLoad(true) ; 
useResFile (oldres) ; 

GetStrSize := size; 
end; 
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{★ ***★★★*★****■**■** *************** RecogFile ********************************* 


* Called when trasnlator receives tm_Recognize. * 

* It is also called by DoName and DoFileConvert. * 

* RecogFile is passed a trnPTR and status record. It should check the file * 

* specified as the source and return either ACCEPT or UNACCEPT as the * 

* function result, depending on whether the file matches the criteria for * 

* acceptance by this routine. Notice how we do not log errors during that * 

* may occur in this function. We only want to know if this translator can * 

* translate this file or not, if it can't for any reason then we do not * 

* accept the file. * 


***************************************************************************) 
Function RecogFile (statRec : statHndl; tmPB : trnPtr) : longint; 
var 

err : OSErr; 
pb : HParamBlockRec; 
pbnew,pbold : WDPBRec; 
temp : OSType; 
size,readsize : longint; 
fref, num ; integer; 
srcopened : boolean; 
oldres : integer; 
begin 

{* check if the file's already been tested *} 

RecogFile := unaccept; 
if tmPB“.tmTested then begin 

if trnPB" .tmAccepted then RecogFile := accept; 

exit (RecogFile); 

end; 

{* check whether we have a resource fork or no *} 
pb.ioNamePtr := Stropb" .tmNames"''.names [0] ; 
pb.ioFDirIndex := 0; 

err := FileOp (FFGetFInfo, fromFS, Spb, statrec, tmpb) ; 

if err noerr then exit(RecogFile); { don't log errors during recognition } 
if pb.ioFlRPyLen - 0 then exit(RecogFile); 

srcopened := false; 

if band(pb.ioFlAttrib,$04) = 0 then begin { if already opened, don't reopen } 

{* now we have to check things out via the resource manager *) 

{* first: set up the volume because the resource manager doesn't allow volume 
AND directory specification *} 
pbold.ioCompletion := NIL; 
pbold.ioNamePtr := NIL; 
err :=■ PBHGetVol (Spbold, false) ; 
if err <> noerr then exit(RecogFile); 
with pbnew do begin 
ioConpletion := NIL; 
ioNamePtr := NIL; 
ioVRefNum := tmpb A .tmfrvref; 
ioWDDirlD := tmpb / '.trnfrpar; 
err :=* PBHSetVol (Spbnew, false) ; 
if err <> noerr then exit(RecogFile); 
end; 

fref := OpenResFile (tmpb A .tmNames AA .names [0]) ; 
err := PBHSetVol(Spbold, false); 

( if the resource fork of the source could not be opened then exit } 
if fref <= 0 then exit(RecogFile); 
srcopened := true; 
end 

else fref := pb.ioFRefNum; 

oldres := CurResFile; 

useResFile(fref); 

num := countlResources('STR#'); 

useResFile(oldres); 

if num > 0 

then RecogFile := accept; 
if srcopened then begin 
CloseResFile(fref); 
end; 

end; { RecogFile } 
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{******★***★*******★************* ReportErr ********************************* 

* Called whenever an error occurs that must be reported to the user log, ie * 

* it is used by almost all of the procedures. * 

* Notice how part of the error message is reported using resources stored * 

* in the AFE resource fork (for err <0 and >-85). AFE includes some stan- * 

* dard strings for these errors, check them out with ResEdit to see if they * 

* fit in your error messages as well. They are in the STR# ID=150 resource * 

*****************************************************i'- k i r ir****i'it***i'*****ir*** } 

Procedure ReportErr(err,doing : integer; statRec : statHndl; trnPB : trnPtr); 

{ err = error code (usually a File manager code, 
doing = the action attempted that caused the error, one of the str_ 
constants declared at the top of this unit ) 

var 

Str : str255; 
oldres : integer; 
begin 

{ save the AFE file ref number of the AFE resource file } 
oldres := curResFile; 

{ use the translator resource file ) 
useResFile(statRec''*.myFRef) ; 

GetlndString(str,statrec**.myID,str_error); 

CallErrLog(str, false, true, trnPB*.tmlogproc) ; 

GetlndString(str,statrec**.mylD,doing); 

CallErrLogtstr, false, true, trnPB* .tmlogproc) ; 
useResFile(oldres); 

{ if appropriate use the error string from the AFE resource STR#150 ) 
if (err < 0) and (err > -85) 

then GetlndString(str,150,-err) 
else GetIndString(str,150,5); 

CallErrLog (str, true, true, trnpb'' .tmlogproc) ; 
end; { ReportErrLog ) 

{********************************* TranStr ********************************** 


* This is the function that provides the interaction between AFE and the * 

* translator. It ALWAYS has the SAME number and types of parameters. * 

* INPUT : Message - this integer describes the opertation requested by * 

AFE for a complete listing of these operations see the * 

* constants under the "Conversion Routine Commands" heading * 

* TranslateData - this is either the default settings for this * 

translator, or a handle to some global data the translator * 

* has allocated. * 

Param - Varies with the message. Usually a pointer to info on * 

source and destination files, or names of translated files. * 

Self - this is a handle to the translation routine itself. * 

It is used to lock the routine in memory while it is in use. * 

* OUTPUT ; NONE * 

* RESULT : Varies with the message. Usually the status of a certain oper * 

ation. If AFE does not explicitly require a result the tran- * 

* slator must return a zero. * 


*»»»*■«•«*********************************„********************************* j 

function TranStr(Message ; integer; VAR translateData : Handle; 

Param : longint; Self : handle) : longint; 
var 

tmpb : trnPtr; 
statRec,statrec2 : statHndl; 
oldres : integer; 
h : handle; 
err : OSErr; 
begin 

hlock (self) ; 

tmpb := POINTER (Param) ; 
statRec := POINTER(translateData); 
case Message of 
tm_Init : begin 

TranStr := Dolnit(translateData,self,trnpb); 
end; 


tm_Finis : begin 

TranStr := DoFinish(translateData); 
end; 
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tm_Appear : begin 

TranStr : = DoAppear(trnpb,statRec); 
end; 

tm_Disappear : begin 

(* tm_D IS APPEAR cleans up any global variables that might have 

* been allocated by tm_APPEAR. ALWAYS returns NoErr. 

*> 

TranStr := noerr; 
end; 

tm_Get : begin 

{* tm_GET returns the current status of this routine as the 

* function result. 

*> 

TranStr := statRec**.myStatus; 
end; 

tm_Set : begin 

(* tm_SET sets the status flag of this routine using the 

* value in PARAM. The new status flag is returned as the 

* function result. 

*} 

statRec**.myStatus := param; 

TranStr := param; 
end; 

tm_Active ; begin 

TranStr := Activate (statRec, tmPBI ; 
end; 

tm_Inactive : begin 

{* tm_INACTIVE indicates that the user wishes to UNcheck this 

* menu item. The routine just clears the active bit in the 

* flags, and then returns the new status flag as the 
' * function result. 

*} 

statRec*'' .myStatus := band (statRec**.myStatus, -1-tmActive) ; 
TranStr := statRec**.myStatus; 
end; 


tm_Recognize : begin 

TranStr := RecogFile(statRec,trnpb); 
end; 

tm_NewName : begin 

TranStr := DoName(statRec,trnpb); 
end; 

tm_File ; begin 

{* tm_FILE is passed a tmPTR in PARAM. It should check 

* the file specified as the source and return either NOERR 

* or UNACCEPT as the function result, depending on whether 

* the file matches the criteria for acceptance by this 

* routine. If acceptable, then tm_FILE should do the actual 

* translations, using the name (or possibly names) specified 

* in the name handle. Any errors encountered during translations 

* should be reported to the user log. Periodically, the 

* status procedure should be called with a (possibly empty) 

* status message and a number between 0 and 100 indicating 

* the percentage complete. This routine will return TRUE 

* most of the time, but can return FALSE if the user has 

* pressed the CANCEL button on the status panel. Because the 

* user can press CANCEL, it is requested that tm_FILE call 

* the status procedure as often as necessary to achieve 

* measure of reasonable feedback. 

*) 

TranStr := DoFileConvert(statRec,trnpb); 
end; 


some 



trn_Load : begin 
{* 

* Do a GETRESOURCE for all of the resources that you might 

* need during a translation. This does not guarantee that 

* a "floppy shuffle" won't be needed, just helps the odds. 

* Load the most likely to be used resources last so they will 

* be the least likely to be purged. 

*} 

oldres := curResFile; 
useResFile(statrec AA .myFRef); 
h := getResource('ICON',statrec AA .myID); 
h := getResource( 1 ICON 1 ,statrec AA .myID+1); 
h := getResource ('ICON', statrec / ' / '.myID+2) ; 
h := getResource (' ICON', statrec AA .myID+3) ; 
h := getResource('DITL',statrec AA .myID); 
h := getResource('DLOG',statrec AA .myID); 
h := getResource(’STR# 1 ,statrec AA .myID); 
useResFile(oldres); 

{ don't bother bringing in the ABOUT text ) 

TranStr := 0; 
end; 

trn_About ; begin 
{* 

* If we want to tell the user about ourselves, we can put up 

* our own dialog (in which case we return zero). If we want 

* nothing done, we can return -1, whereupon Apple File Exch will 

* inform the user that no information is available. 

* If we want Apple File Exch to display the information, we can give 

* it a (positive) resource ID of a TEXT resource containing 

* information about us. 

*} 

TranStr := statrec AA .mylD; 
end; 

trn_GetSettings : begin 
{* 

* With this message, Apple File Exch is requesting a handle filled 

* with data that can be stored in a document. Apple File 

* Exchange allows the user to save and restore default settings 

* ("preferences", if you will) so that the user can launch 

* the program and have each translation be in a state that 

* they are familiar with. We have to do the NEWHANDLE call 

* to create a handle of the correct size, Apple File Exch will 

* dispose it later. If this call is not supported, return 

* NIL or some (negative) error code. 

*} 

h := translateData; 

( Create a new handle that points to a COPY of the global data ) 
err := HandToHand(h); { see Inside Mac vol II, p374 for details } 
if err = noerr 

then TranStr := ORD4(h) 
else TranStr := err; 
end; 
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trn_SetSettings : begin 
{* 

* With this message, Apple File Exch is passing a handle filled 

* with data that indicates a default setting. Apple File Exchange 

* allows the user to save and restore default settings 

* ("preferences", if you will) so that the user can launch 

* the program and have each translation be in a state that 

* they are familiar with. Apple File Exch will dispose of this 

* handle later (do not do so yourself). If this call is 

* not supported, return NIL or some (negative) error code. 

*} 

h := POINTER(param); 

{ If for some reason AFE does not send a pointer to the correct 
data then do not change the current set up } 
if GetHandleSize(h) <> sizeof(statusRec) then TranStr := 0 
else with statrec AA do begin 
statrec2 := POINTER (h) ; 
mystatus := statrec2 AA .mystatus; 
ftype := statrec2 AA .ftype; 
fkind := statrec2 AA .fkind; 
end; 
end; 
end; 

hunlock (self) ; 
hpurge(self) ; 
end; 

end. 
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AFETrans.p 

Unit AFETrans; 


INTERFACE 


Uses 

{$LOAD MacLoad.L} MemTypes,QuickDraw,oslntf,toolIntf,packIntf,macPrint,script; 
CONST 

{* translator routine commands *} 
trn_Init = 0; { do any translator routine initialization ) 

tm_Finis = 1; { do any clean up and disposal } 

trn_Get =2; { Return current status } 

trn_Set =3; { Set current status } 
trn_Active = 4; { User has requested item be checked in menu } 

trn_ In active = 5; { User has requested item be unchecked in menu } 

tm_NewName =6; {If recognized, return new name for selected file ) 
tm_File =7; { If recognized, convert the selected file } 
tm_Recognize = 8; { Return NoErr if selected file is recognized } 
tm_Appear = 9; { This routine is now listed in a menu } 

-tn^Disappear = 10; { This routine is no longer listed in a menu } 
tm_Load = 11; { Pre-load any resources you might need } 
tm_About = 12; { Provide "About this translator" information } 
tm_GetSettings=13; { Get default information about the translator } 
tm_SetSettings=14; { Set default information about the translator } 

{* translator status bits *} 
tmActive = $0001; { item is checked } 
trnGray = $0002; { item is grayed-out } 
trnBold = $0010; { item is bold } 
tmltalic » $0020; { item is italicized } 
tmUnderline= $0040; { item is underlined } 
tmOutline = $0080; { item is outlined } 
tmShadow = $0100; { item is shadowed } 

tmAbout = $0200; { About information is available for the item) 
tmUserl = $1000; { user bit 1 } 

tmUser2 = $2000; { user bit 2 } 

tmUser3 = $4000; { user bit 3 } 

{* miscellaneous constants *} 

maxdestnames =15; 

accept = noerr; 
unAccept = 1; 
tmCancel = 2; 

{* File system op codes *) 

FFGetVInfo = 1; FFSetVInfo = 2; FFFlushVol = 5; 

FFOpen = 9; FFOpenRF = 10; FFLockRange = 11; 

FFUnLockRange = 12; FFRead = 13; FFWrite = 14; 

FFGetFPos = 15; FFSetFPos = 16; FFGetEOF = 17; 

FFSetEOF = 18; FFAllocate = 19; FFAllocContig = 20; 

FFFlushFile = 21; FFClose = 22; FFCreate = 23; 

FFDirCreate = 24; FFDelete = 25; FFGetFInfo = 26; 

FFSetFInfo = 27; FFSetFLock = 28; FFRstFLock = 29; 

FFSetFVers = 30; FFRename = 31; FFGetCatlnfo = 32; 

FFSetCatlnfo = 33; FFOpenWD = 35; FFCloseWD = 36; 

FFGetWDInfo = 37; FFOKFName = 41; FFMakeFName = 47; 

FFXGetCatlnfo = 50; FFXSetCatlnfo = 51; 

foreignFS = '4NFS'; 
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{* Extended Catlnfo constants *} 

mdos = 'mdos'; 
pdos = 'pdos'; 

{ProDOS access bits} 

pdReadable = $01; { File may be read } 

pdWritable = $02; { File may be written to } 

pdChanged = $20; { File has changed since last backup } 

pdRename = $40; { File may be renamed } 

pdDestroy = $80; { File may be destroyed } 

pdNormal = $C3; { A normal ProDOS file } 

pdLocked = $01; { A locked ProDOS file } 

{ProDOS storage types} 

pdSeedling = $01; { File is a seedling, only one data block } 

pdSapling = $02; { File is a sapling, 2 to 256 data blocks } 

pdTree = $03; { File is a tree, 257 to 32768 data blocks } 

pdSubDir = $0D; { File is a subdirectory } 

{ProDOS version numbers} 

ProDoslJ) = 0; { ProDOS 1.0 } 

{MSDOS Attribute bits} 

msReadOnly = $01; { File is read-only } 

msHidden = $02; { File is hidden } 

msSystem = $04; { File is a system file } 

msVolume = $08; { Directory is the root } 

msSubDir = $10; { File is a subdirectory } 

msArchive= $20; { File has been written to and closed } 

{**************************************************** 

★ 

* constants for tprocs 

★ 

★ ★★★★★★★★★★★★★★★★★********************************* J 

tDstTooShort = -501; 

cfMacintosh = 0; 
cfASCIi = 1; 
cfIBMPC = 2; 

translnit = 0; 
transDone = 1; 
translotohi = 2; 
transhitolo = 3; 

trMultiDestFont = 1; 
trMultiDestCountry = 2; 
trNonOnetoOne = 4; 
trOverStrike = 8; 

TypE 

nameREC = RECORD 

namecnt : integer; 

names ; array[0..maxdestnames] of str255; 
end; 

nameptr = "nameRec; 
namehdl = "nameptr; 
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translateRec = RECORD 

tmLogproc : procptr; { pointer to error log procedure } 
tmstatproc : procptr; { pointer to status procedure } 
tmfrID : integer; { resource ID of source FS } 

tmtoID : integer; { resource ID of dest FS } 

trnfrData : ptr; { pointer to source FS global data } 
trntoData : ptr; { pointer to dest FS global data } 
tmResrv ; integer; { used by InterFile } 
trnfrVRef : integer; { volume ref of source } 
trntoVRef : integer; { volume ref of dest } 
tmfrPar : longint; { parent ID of source } 

tmtoPar : longint; { parent ID of dest } 

tmnames : namehdl; ( handle to names of source/dest files} 
trnTested : boolean; { TRUE if you've already looked at this 
file for recognition } 

tmAccepted : boolean; {if TRNTESTED is true, this flag shows 
whether you recognized the file } 
tmCountry : integer; { country ID } 

END; 

tmPtr = "'translateRec; 

{* parameter blocks for extended Catlnfo calls *} 

XFSType = (Mac,ProDOS,MSDOS); 

XCInfoPtr = A XCInfoPBRec; 

XCInfoPBRec = RECORD 

{ In the memo this was descrived as a pointer not a record } 
CInfo: CInfoPBRec; 

CASE xfs : XFSType OF 
Mac : 

(filler3 : longint); 

ProDOS : 

(auxtype : integer; { ProDOS auxilary file type } 
access ; signedbyte;{ read,write pern etc. } 
storagetype ; signedbyte;{ seedling,sapling, etc ) 
version ; signedbyte;{ version ProDOS used } 
minvers : signedbyte);{ earliest ProDOS version useable } 
MSDOS : 

(attrib ; signedbyte; { read,write, hidden, etc } 
filler4 : signedbyte); 

END; 

pdosHndl = A pdosPtr; 
pdosPtr = A pdosRec; 
pdosRec = RECORD 
auxtype : integer; 
access : signedbyte; 
storagetype : signedbyte; 
version : signedbyte; 
minvers : signedbyte; 

END; 


mdosHndl = A mdosPtr; 
mdosPtr = A mdosRec; 
mdosRec = RECORD 

attrib : signedbyte; 
filler3 : signedbyte; 
END; 

TPRCEntry = RECORD 
tprcID : integer; 
curCharFam : integer; 
altCountry : integer; 
altCharFam : integer- 
end; 
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tprf = RECORD 

lastEntry : integer; 

reserved : array(1..31] of integer; 

tprocs : array[1..1000] of TPRCEntry; 

end; 

tprfPtr = ■'tprf; 

tprfHndl = A tprfPtr; 

header = RECORD 
branch : longint; 
sig ; resType; 
resnum : integer; 
versnum : integer; 
vers : string[15]; 
flags : integer; 
loCntry : integer; 
loCFam : integer; 
hiCntry : integer; 
hiCFam : integer; 
hdrrsrv : array[0..3] of longint; 
end; 

hdrPtr = ^header; 

hdrHndl = 'hdrPtr; 

TransText = RECORD 
trPtr : Ptr; 
trLen : Longint; 
trFont : integer; 
end; 

TransPB = RECORD 
verb : integer; 
featureflags: integer; 
result : OSErr; 
newCntry : integer; 
srcText : TransText; 
dstText ; TransText; 
tpRsrv ; array[0..3] of longint; 
end; 


function CallFSfmsg : integer; fsdata : ptr; pb :ptr; 

async : boolean; fsroutine : handle) : OSErr; 
INLINE $2057,$2050,$4E90; 


procedure CallLog(str : str255; cr : boolean; Indent : boolean; Logproc : procptr); 
INLINE $205F, $1F5F, $0001, $4E90; 

procedure CallErrLog(str : str255; cr : boolean; Indent : boolean; Logproc : procptr); 
INLINE $205F, $1F5F, $0001, $002F, $0080, $0001, $4E90; 

function CallStat(statmsg ; str255; statpct ; integer; destfnum : integer; 
statproc : procptr) : boolean; 

INLINE $205F, $4E90; 

function CallTProc(VAR params : TransPB; self : hdrHndl) : OSErr; 

INLINE $2057,$2050,$4E90; 


IMPLEMENTATION 


end. 
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Example.a 


File: Example.a 

Copyright 1986,1987 by Apple Computer, Inc. All Rights Reserved. 


EXAMPLE TRANSLATION ROUTINE HEADER FOR APPLE FILE EXCHANGE 


The file provides the required header for a translator. 


PRINT 

INCLUDE 

INCLUDE 

INCLUDE 

INCLUDE 

INCLUDE 

PRINT 


OFF 

■Traps.a' 
'ToolEqu.a' 
'QuickEqu.a' 
■SysEqu.a' 

'SysErr.a' 

CN 


MAIN 

IMPORT TranStr ; this is the procedure name of the Pascal code 


HEADER 


STRING AS IS 
jmp TranStr 
dc.l 'tran' 
dc.w 4000 
dc.w 1 

STRING PASCAL 
dc.w 'l.OAl' 
dc.l SOOOOFFFF 
dc.l 0 


; branch to Pascal Code 
; signature 

; resource number (decimal) 

; my version number 

; ASCII version of version 
; Indicates we support all calls 
; Reserved 


ENDMAIN 

end 
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Example.r 

/* Example Translation inclusion Resource Definition File */ 
/* */ 


/* include any static resources like dialogs, strings, etc. */ 
include "Example.rsrc"; 

/* include the code itself */ 

include ":Objects:Example.tmp" 'MCMC' (4000) as 'MCMC' (4000, "STR# Resources to Text...",PURGEABLE) ; 

/* include the About text */ 
read 'TEXT' (4000) "Example.txt"; 

/* Create a STR# resource containing all the error strings our translator */ 

/* produces. The str_xxxxx are the constants used to reference each string */ 

/* in Exanple.p */ 
resource 'STR#' (4000) ( { 

/* str_error =1; */ "An error occurred while 
/* str_creating = 2; */ "creating the destination file: 

/* str_opensrc =3; */ "opening the source file: 

/* str_opendst = 4; */ "opening the destination file: '•; 

/* str_getfinfo = 5; */ "getting information about the file: 

/* str_setfinfo = S; */ "setting the file type of the destination file: 

/* str_reading = 7; */ "reading in the source file: "; 

/* str_writing = 8; */ "writing out the destination file: 

/* str_copying = 9; */ "Copying STR# resources.."; 

/* str_initing =10; */ "initializing the translator '“; 

/* str_period = 11; */ 

/* str_cant = 12; */ "It cannot translate from '"; 

/* str_to = 13; */ "' to 

/* str_delsrc = 14; */ "deleting the original file (your translated data is in the file 
S$SAFE-TEMP$$$): "; 

/* str _rendst = 15; */ "renaming the destination file (your translated data is in the file 
S$SAFE—TEMP$$$): "; 

/* str_numstrings = 16; */ "Number of STR# resources in this file: "; 

/* str_stringRes =17; */ "String Resource Number " 

} ); 

/* The following is used to create a different icon for the translator */ 

/* The new icon was created by using ResEdit to modify the standard */ 

/* translator icon. For more detail see Inside Mac III, pp.10-13 */ 

/* define the resource type? as a string type */ 

/* The file "Signature.r" is created by the make file ("Example.make") and contains */ 

/* the signature resource (in this case, of type 'exmp') necessary for displaying */ 

/* a different icon */ 

/* The text in the "exmp" resource will be diplayed when a Get Info is done on the */ 

/* translator in the Finder*/ 

#include ": objects Signature, r" 
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/* The BNDL id number (0) is necessary but not important, it is never used */ 
resource 'BNDL' (0) { 

'exmp', 

0 , 

{ 

/* Map the local icon number 0 to the actual icon resource 128 */ 

/* we use ICN# instead of ICON so that the mask is included, the */ 

/* mask is how the icon looks highlighted */ 

'ICN#', 

{ 

0, 128 

}, 

/* Map local FREF 0 to FREF 128 */ 

’FREF', 

{ 

0, 128 

} 

) 


/* Create a file reference resource of id=128 that associates type VISA */ 
/* with the icon of local ID = 0 ; */ 
resource 'FREF' (128) { 

'VISA', 

0 . 

im 

); 

/* for this icon to be used with the translator the bundle bit */ 

/* must be set. This is done with the setfile -a B 'Example Tran' */ 

/* statement in MPW after building the translator with rez */ 
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Example, file 7 


# 

# The example translator sources should live in a folder called 

# "ExampleTrans" within the MPW folder. There should also be 

# a folder within "ExampleTrans" called "Objects'' which will contain 

# the object files and other 'deletable' files. 

# 

# In the MAKE command line, the '-d' option is used to set the version 
$ number. In the next command line, the computer will sound two notes 

# when it is done: if the notes go up, an error occurred; if the notes 
ff go down, all is well. 

# 

directory {MPW(ExampleTrans 

make -f Example.make 'Example Translator' -d vers='1.0B4' >doit 
doit || (beep 1320; beep 880) 
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doit 


echo "Compiling Example.p" 

Pascal Example.p -o :objects:Example.p.o 

echo "Linking Example Translator" 

Link -1 :objects:Example.a.o :objects:Example.p.o 3 
"HD20:MPW:PLibraries:“Paslib.o 3 
"HD20:MPW:Libraries:"Interface.o 3 
—rt MCMC=4000 -ra Main=0 -m 3 
-t 'TEMP' -c '????' 3 

-o :objects:Example.tmp >:objects:Examp.map 
echo "Building Example Translator vl.0B4" 

echo "/* Signature resource build file */" >:objects:signature.r 
echo "type , exmp' as 'STR »:objects:signature.r 
echo "resource 1 exmp 1 (O.purgeable) 3{ " >> :objects : signature . r 
echo "3"Example Translator, vl.0B4, 'date -d'3" n >>:objects:signature.r 
echo "3}; n >>:objects:signature.r 
rez types.r Example.r 3 
-t VISA -c exmp 3 
-o ‘Example Translator 1 
setfile -a Bi ‘Example Translator 1 
(beep 880; beep 1320) 
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Example.make 

Obj = :objects: 

AOptions = 

POptions = 

LinkOptions = -1 

vers = temp 

Examp = {Obj}Example.a.o {Obj}Example.p.o 
(Obj) f : 

.a.o f .a 

echo "Assembling {DepDir}{Default}-a" 

{Asm} {AOptions} {DepDir}{Default}.a -o {TargDir}{Default}.a.o 
•p.o f .p 

echo "Compiling {DepDir}{Default}.p" 

{Pascal} {POptions} {DepDir}{Default}.p -o {TargDir}{Default}.p.o 


'Example Translator' / {Obj}Example.tmp Example.r Example.rsrc Example.make 
echo "Building Example Translator v{vers}" 

echo "/* Signature resource build file */" >{Obj}signature.r 
echo "type 'exmp' as 'STR »{Obj}signature.r 

echo "resource 'exmp' (O.purgeable) 3{ " >>: objects : signature . r 
echo "3"Example Translator, v{vers}, ‘date -d"3"" >>{Obj}signature . r 
echo "3};" >>{Obj}signature.r 
rez types.r Example.r 3 
-t VISA -c exnp 3 
-o 'Example Translator' 
setfile -a Bi 'Example Translator' 

(beep 880; beep 1320) 

{Obj}Example.tmp f {Examp} 

echo "Linking Example Translator" 

Link {LinkOptions} {Exanp} 3 
”{PLibraries} n Paslib.o 3 
”{Libraries)"Interface.o 3 
-rt MDMC=4000 -ra Main=0 -m 3 
-t 'TEMP' -c '????' 3 
-o :objects:Example.tmp >{Obj}Examp.map 
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Appendix D 


Differences Between the 
U.S. and International Versions 
of Apple File Exchange 


There are currently two versions of Apple File Exchange: 

□ the U.S. version (version 1.0.1) 

□ the international version (version Zl-1.0.1). 

Most of the differences between these two versions are in the ways they handle 

extended character sets: 

□ When users select any of the text translators in the international version, a dialog 
box appears. In this dialog box, users can select whether Apple File Exchange 
interprets characters in the extended character set as control characters or as 
accented characters. 

□ When a user translating an MS-DOS file selects the “Remove unnecessary control 
characters” option, the U.S. version suppresses all characters with character codes 
greater than 128 hexadecimal. The international version translates characters in 
MS-DOS text files with character codes greater than 128 hexadecimal if they 
represent accented characters. 

□ When a user translating a ProDOS text file selects the “Make control characters 
visible” option, the U.S. version displays control characters with character codes 
greater than 128 hexadecimal. The international version does not display these 
characters; this permits the display of accented characters that are part of the 
Apple IIGS extended character set. 

The international version also provides a menu (the Country menu) that lets users 

identify the version of system software for the Macintosh that they’re using. This makes 

it possible to use one version of Apple File Exchange in all countries. 














Appendix E 


Apple File Exchange 
TProcs 


The tables in this appendix list the transliterations performed by Apple File Exchange 
TProcs. Most of these tables include two kinds of transliterations: 

□ single-character transliterations that are performed when the “Change to closest 
single character” option for a translator is selected 

□ multiple-character transliterations where certain characters are replaced by more 
than one character 

Only the tables for U.S. English TProcs list all transliterations. Other tables list only 
the characters that are different from the corresponding U.S. English table. 

For information about TProcs, see Chapter 2, “Writing Translators.” 


Macintosh to MS-DOS transliterations 

The following tables list the transliterations from the Macintosh character set to the 
corresponding MS-DOS character set. 


Macintosh to MS-DOS: U.S. English 

This TProc is used for U.S. English as well as for Australian English, British English, 
Canadian French, Dutch, Finnish, Flemish, French, German, Spanish, Swedish, Swiss 
French, and Swiss German. 


Ona to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

A 

128 

A 

142 

A 

142 

A 

129 

A 

143 

A 

143 

C 

130 

<? 

128 

C 

128 

E 

131 

E 

144 

E 

144 

N 

132 

N 

165 

N 

165 

6 

133 

6 

153 

6 

153 

u 

134 

u 

154 

u 

154 

a 

135 

a 

160 

a 

160 

a 

136 

a 

133 

a 

133 
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One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

a 

137 

a 

131 

a 

131 

a 

139 

a 

97 

a- 
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140 

4 

134 

4 

134 

9 

141 

9 

135 

9 
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142 

e 

130 

€ 
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6 
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b 

138 

b 

138 

e 

144 

e 

136 

e 

136 

e 

145 

e 

137 

e 

137 

1 

146 

1 

l6l 

1 

l6l 

1 

147 

i 

141 

l 

141 

I 

148 

l 

140 

1 

140 

Y 

149 

T 

139 

i* 
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n 
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N 

165 
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6 

151 

6 

162 

6 

162 

6 

152 

6 

149 

6 

149 

6 

153 

6 

147 

6 

147 

6 

154 

6 

148 

6 

148 

6 

155 

O 

111 

o- 


u 

156 

u 

163 

u 

163 

u 

157 

u 

151 

u 

151 

u 

158 

u 

150 

u 

150 

ii 

159 

ii 

129 

ii 

129 

t 

160 

T 

194 

T 

194 

O 

l6l 

O 

248 

O 

248 


162 

<t 

155 


155 

£ 

163 

£ 

156 

£ 

156 

5 

164 

$ 

36 

$ 

36 

• 

165 

• 

249 

• 

249 


166 

P 

80 

PI 


s 

167 

S 

225 

fi 

225 

® 

168 

r 

114 

Cr) 


© 

169 

c 

99 

CO 


TM 

170 

t 

116 

tm 


* 

171 

» 

34 

» 

34 

" 

172 


46 

, , 



173 

= 

6l 

=/ 


/E 

174 


146 


146 

0 

175 

0 

237 

0 

237 

oo 

176 

OO 

236 

OO 

236 

± 

177 

+ 

241 

+ 

241 

< 

178 

< 

243 

< 

243 

> 

179 

> 

242 

> 

242 

¥ 

180 

¥ 

157 

¥ 

157 

Fl 

181 

M- 

230 

M- 

230 

a 

182 

a 

235 

a 

235 

I 

183 

i 

228 

i 

228 

n 

184 

it 

227 

n 

227 

jr 

185 

rt 

227 

7C 

227 

J 

186 

J 

244 

J 

224, 245 

a 

187 

a 

166 

a 

166 

9 

188 

9 

167 

9 

167 
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One to single character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

G 

189 

a 

234 

a 

234 

3E 

190 

X 

145 

as 

145 

0 

191 

0 

237 

o/ 


i 

192 

i 

168 

i 

168 

i 

193 

i 

173 

i 

173 


194 

-1 

170 


170 

V 

195 

V 

251 

V 

251 

/ 

196 

f 

159 

f 

159 

ss 

197 

= 

247 

= 

247 

A 

198 

A 

127 

< > 


« 

199 

m 

174 

« 

174 

» 

200 

» 

175 

» 

175 

... 

201 


46 

... 


blank 

202 

blank 

32 

blank 

32 

A 

203 

i 

133 

i 

133 

A 

204 

A 

65 

A- 


6 

205 

O 

79 

o~ 


CE 

206 

O 

79 

OE 


oe 

207 

o 

111 

oe 


- 

208 

- 

45 

- 

45 

- 

209 

— 

196 

— 

196 

a 

210 

* 

34 


34 

n 

211 

it 

34 

H 

34 

i 

212 

i 

39 

1 

39 

» 

213 

t 

39 

t 

39 

+ 

214 

+ 

246 

+ 

246 

0 

215 

< 

60 

< > 


y 

216 

y 

152 

y 

152 

Y 

217 

y 

152 

y 

152 

l 

218 

/ 

47 

/ 

47 

a 

219 

o 

111 

o 

111 

< 

220 

< 

60 

< 

60 

> 

221 

> 

62 

> 

62 

fi 

222 

f 

102 

fl 


fl 

223 

f 

102 

fl 


* 

224 

4= 

216 

4= 

216 


225 


250 


250 

i 

226 

» 

44 

* 

44 

n 

227 

> 

44 

i » 


%o 

228 

% 

37 

% 

37 

A 

229 

a 

131 

a 

131 

E 

230 

e 

136 

e 

136 

A 

231 

a 

160 

a 

160 

E 

232 

e 

137 

e 

137 

E 

233 

6 

138 

£ 

138 

I 

234 

1 

161 

1 

l6l 

! 

235 

I 

140 

l 

140 

I 

236 

"i 

139 

l 

139 

i 

237 

I 

141 

i 

141 


(continued) 
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One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

6 

238 

6 

162 

6 

162 

6 

239 

6 

147 

6 

147 

* 

240 

■ 

219 

<Apple> 


0 

241 

6 

149 

6 

149 

u 

242 

u 

163 

u 

163 

u 

243 

u 

150 

u 

150 

u 

244 

u 

151 

u 

151 

1 

245 

i 

105 

i 

105 


246 

A 

94 

A 

94 

n 

247 

- 

126 

- 

126 

~ 

248 

- 

45 

- 

45 

w 

249 

» 

44 

t 

44 


250 


250 


250 


251 

□ 

248 

a 

248 

> 

252 

1 

44 

» 

44 


253 

If 

34 

If 

34 

1 

254 

» 

44 

t 

44 

V 

255 

V 

255 

V 

255 

Macintosh to MS-DOS: Danish 



This transliteration is used only for Danish. It is the same as the U.S. English 

Macintosh to MS-DOS transliteration except for the characters listed. 



One to single character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

n 

150 

n 

164 

ii 

164 

D: 

162 

c 

99 

<cent> 


* 

173 

# 

35 

# 

35 

0 

175 

0 

157 

0 

157 

¥ 

180 

¥ 

157 

Y 

89 

0 

191 

0 

155 

0 

155 

A 

198 

A 

127 

A 

127 

A 

203 

A 

65 

A' 


Y 

217 

Y 

89 

YE 


%o 

228 

% 

37 

%o 


A 

229 

A 

65 

AA 


E 

230 

E 

69 

EA 


A 

231 

A 

65 

A' 


E 

232 

E 

69 

E" 


E 

233 

E 

69 

E' 


! 

234 

I 

73 

V 


! 

235 

I 

73 

IA 


i 

236 

I 

73 

I" 


i 

237 

I 

73 

r 


6 

238 

O 

79 

O' 


6 

239 

O 

79 

OA 


0 

241 

o 

79 

O' 


u 

242 

u 

85 

U’ 


u 

243 

u 

85 

UA 


u 

244 

u 

85 

IT 
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Macintosh to MS-DOS: Italian 

This transliteration is used only for Italian. It is the same as the U.S. English Macintosh 
to MS-DOS transliteration except for the characters listed. 


One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

n 

150 

n 

164 

n 

164 

5 

164 

@ 

64 

@ 

64 

® 

168 

R 

82 

CR) 


© 

169 

C 

67 

CC) 


TM 

170 

T 

84 

TM 


i 

226 

1 

39 

I 

39 

n 

227 

1 

39 

I 

39 

%o 

228 

o 

111 

%o 



Macintosh to MS-DOS: Norwegian 

This transliteration is used only for Norwegian. It is the same as the U.S. English 
Macintosh to MS-DOS transliteration except for the characters listed. 


One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

<t 

162 

c 

99 

cent 


0 

175 

0 

157 

0 

157 

¥ 

180 

y 

121 

yen 


0 

191 

0 

155 

0 

155 


Macintosh to MS-DOS transliterations 
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MS-DOS to Macintosh transliterations 

The following tables list the transliterations from one of the MS-DOS character sets to 
the Macintosh character set. 


MS-DOS to Macintosh: U.S. English 

This transliteration is used for U.S. English as well as for Australian English, British 
English, Canadian French, Dutch, Flemish, French, Swedish, and Swiss French. 


One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

c 

128 

c 

130 

c 

130 

ii 

129 

u 

159 

ii 

159 

e 

130 

e 

142 

e 

142 

a 

131 

a 

137 

a 

137 

a 

132 

a 

138 

a 

138 

a 

133 

a 

136 

a 

136 

4 

134 

4 

140 

4 

140 

9 

135 

9 

141 

9 

141 

£ 

136 

e 

144 

e 

144 

e 

137 

e 

145 

e 

145 


138 

6 

143 

S 

143 

i 

139 

i 

149 

i 

149 

I 

140 

t 

148 

1 

148 

i 

141 

i 

147 

I 

147 

A 

142 

A 

128 

A 

128 

A 

143 

A 

129 

A 

129 

E 

144 

£ 

131 

£ 

131 

ae 

145 

ae 

190 

ae 

190 

y£ 

146 

M 

174 

/E 

191 

6 

147 

6 

153 

6 

153 

6 

148 

6 

154 

6 

154 

6 

149 

6 

152 

6 

152 

u 

150 

u 

158 

u 

158 

u 

151 

u 

157 

u 

156 

y 

152 

y 

216 

y 

216 

6 

153 

o 

133 

o 

133 

u 

154 

0 

134 

u 

134 


155 

t 

162 

<t 

162 

£ 

156 

£ 

163 

£ 

163 

¥ 

157 

¥ 

180 

¥ 

180 

Pts 

158 

P 

80 

Pt 


f 

159 

/ 

196 

/ 

196 

a 

160 

Z 

135 

a 

135 

l 

161 

i 

146 

l 

146 

6 

162 

6 

151 

6 

151 

u 

163 

u 

156 

u 

156 

n 

164 

n 

150 

h 

150 

N 

165 

N 

132 

N 

132 

i 

166 

* 

187 

a 

187 

g 

167 

g 

188 

g 

188 


E-6 Appendix E: Apple File Exchange TProcs 




One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

i 

168 

i 

192 

i 

192 

comer 

169 

- 

209 

1- 


“1 

170 


194 

"1 

194 

1/2 

171 

2 

50 

1/2 


1/4 

172 

4 

52 

1/4 


i 

173 

i 

193 

i 

193 

« 

174 

« 

199 

« 

199 

» 

175 

» 

200 

» 

200 

oo 

224 

a 

97 

a 

97 

IS 

225 

IS 

167 

13 

167 

r 

226 

-i 

194 

l-> 


7C 

227 

rt 

185 

it 

185 

I 

228 

I 

183 

I 

183 

CT 

229 

o 

111 

<sigma> 


4 

230 

4 

181 


181 

Y 

231 

t 

160 

t 

160 

O 

232 

□ 

219 

<phi> 


e 

233 

9 

188 

9 

188 

a 

234 

Cl 

189 

Cl 

189 

a 

235 

a 

182 

a 

182 

oo 

236 

oo 

176 

oo 

176 

0 

237 

0 

175 

0 

175 

e • 

238 

E 

69 

<epsilon> 


n 

239 

U 

85 

U 

85 

= 

240 

= 

61 

s 

61 

± 

241 

± 

177 

± 

177 

> 

242 

> 

179 

> 

179 

< 

243 


178 

£ 

178 

J 

244 

J 

186 

J 

186 

J 

245 

J 

186 

J 

186 

+ 

246 

+ 

214 

4- 

214 

3S 

247 

ss 

197 

sa 

197 

0 

248 

O 

l6l 

o„ 

l6l 

• 

249 

• 

165 

• 

165 

. 

250 


46 


46 

V 

251 

V 

195 

V 

195 

n 

252 

n 

110 

A n 


2 

253 

2 

50 

A2 



MS-DOS to Macintosh transliterations 
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MS-DOS to Macintosh: Danish 

This transliteration is used only for Danish. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the characters listed. 


One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

it 

155 

0 

191 

0 

191 

¥ 

157 

0 

175 

0 

175 

a 

224 

a 

97 

<alfa> 


r 

226 

G 

71 

<GAMMA> 


a 

229 

s 

115 

<sigma> 


T 

231 

t 

116 

<tau> 

116 

O 

232 

F 

70 

<PHI> 


0 

233 

T 

84 

<THETA> 


0 

237 

0 

191 

0 

191 

e 

238 

e 

101 

<epsilon> 


n 

239 

A 

94 

<fa£lles> 


= 

240 

= 

61 

== 



MS-DOS to Macintosh: Finnish 


This transliteration is used only for Finnish. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the character listed. 


Source 

character 


One to single character 
Source Destination Destination 

value character value 


One to multiple characters 
Destination Destination 
character value 




232 □ 219 <pii> 


MS-DOS to Macintosh: German 

This transliteration is used only for German and Swiss German. It is the same as the 
U.S. English MS-DOS to Macintosh transliteration except for the characters listed. 


One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

r 

226 

— t 

194 

<gamma> 


a 

229 

O 

111 

<Sigma> 


T 

231 

t 

160 

<tau> 


O 

232 

a 

219 

<Phi> 


9 

233 

a 

188 

<theta> 


€ 

238 

E 

69 

<Epsilon> 


n 

239 

U 

85 

<intersection> 
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MS-DOS to Macintosh: Italian 

This transliteration is used only for Italian. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the character listed. 


One to single character One to multiple characters 


Source 

character 

Source 

value 

Destination 

character 

Destination 

value 

Destination 

character 

Destination 

value 

<T 

229 

o 

111 

<SIGMA> 



MS-DOS to Macintosh: Norwegian 

This transliteration is used only for Norwegian. It is the same as the U.S. English 
MS-DOS to Macintosh transliteration except for the characters listed. 


One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

0 

155 

0 

191 

0 

191 

0 

157 

0 

175 

0 

175 

O 

232 

□ 

219 

<pi> 


6 

238 

E 

69 

<ypsilon> 



MS-DOS to Macintosh: Spanish 

This transliteration is used only for Spanish. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the character listed. 




One to single character 

One to multiple characters 

Source 

character 

Source 

value 

Destination 

character 

Destination 

value 

Destination 

character 

Destination 

value 

6 

238 

E 

69 

<6psilon> 



MS-DOS to Macintosh: Swedish 

This transliteration is used only for Swedish. It is the same as the U.S. English MS-DOS 
to Macintosh transliteration except for the character listed. 

One to single character One to multiple characters 

Source Source Destination Destination Destination Destination 

character value character value character value 

® 232 a 219 <fi> 


MS-DOS to Macintosh transliterations 
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Macintosh to ProDOS transliterations 

The following tables list the transliterations from the Macintosh character set to the 
corresponding ProDOS character set. 


Macintosh to ProDOS: U.S. English 


This transliteration is used for U.S. English as well as for Australian English. 



One to single character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

A 

128 

A 

65 

A" 


A 

129 

A 

65 

AA 


C 

130 

C 

67 

c, 


E 

131 

E 

69 

E" 


N 

132 

N 

78 

N~ 


6 

133 

O 

79 

O" 


U 

134 

u 

85 

U" 


a 

135 

a 

97 

a' 


a 

136 

a 

97 

a' 


a 

137 

a 

97 

aA 


a 

138 

a 

97 

a" 


a 

139 

a 

97 

a~ 


A 

140 

a 

97 

aa 


S 

141 

c 

99 

c, 


6 

142 

e 

101 

e' 


d 

143 

e 

101 

e' 


e 

144 

e 

101 

eA 


e 

145 

e 

101 

e" 


1 

146 

i 

105 

i' 


i 

147 

i 

105 

i' 


t 

148 

i 

105 

iA 


Y 

149 

i 

105 

i" 


n 

150 

n 

110 

n~ 


6 

151 

o 

111 

o' 


6 

152 

o 

111 

o' 


6 

153 

o 

111 

oa 


6 

154 

o 

111 

o" 


6 

155 

o 

111 

o~ 


u 

156 

u 

117 

u' 


u 

157 

u 

117 

u' 


u 

158 

u 

117 

UA 


u 

159 

u 

117 

u" 


t 

160 

t 

116 

t 

116 

0 

l6l 

o 

111 

<degrees> 


<t 

162 

c 

99 

<cents> 


£ 

163 

L 

76 

<pound> 


s 

164 

$ 

36 

$ 

36 

• 

165 

o 

111 

• 

42 


166 

p 

80 

PI 


s 

167 

B 

66 

B 

66 

® 

168 

r 

114 

Cr) 
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One to single character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

© 

169 

c 

99 

TM 

170 

t 

116 

* 

171 

i 

39 

** 

172 


46 

* 

173 

= 

6l 

/E 

174 

A 

65 

0 

175 

O 

79 

CO 

176 

% 

37 

± 

177 

+ 

43 

< 

178 

< 

60 

> 

179 

> 

62 

¥ 

180 

Y 

89 

P 

181 

u 

117 

d 

182 

d 

100 

I 

183 

S 

83 

n 

184 

P 

80 

n 

185 

P 

112 

J 

186 

S 

83 

i 

187 

a 

97 

9 

188 

o 

111 

n 

189 

O 

79 

as 

190 

a 

97 

0 

191 

o 

111 

i 

192 

? 

63 

i 

193 

! 

33 

I 

194 

- 

45 

V 

195 

V 

118 

/ 

196 

f 

102 

as 

197 

= 

61 

A 

198 

d 

100 

« 

199 

< 

60 

» 

200 

> 

62 

... 

201 


46 

blank 

202 

blank 

32 

A 

203 

A 

65 

A 

204 

A 

65 

6 

205 

O 

79 

CE 

206 

O 

79 

oe 

207 

o 

111 

- 

208 

- 

45 

- 

209 

- 

45 

« 

210 

» 

39 

»» 

211 

» 

39 

( 

212 

1 

39 

» 

213 

1 

39 

+ 

214 

/ 

47 

0 

215 

o 

111 

y 

216 

y 

121 

Y 

217 

Y 

89 

i 

218 

/ 

47 

□ 

219 

o 

111 


One to multiple characters 
Destination Destination 
character value 

Cc) 

tm 

' 39 

=/ 

AE 

O/ 

<infinity> 

+- 
< = 

> = 

Y= 

u 117 

d 100 

<SIGMA> 

PI 

Pi 

<integrai> 
a _ 
o _ 

<omega> 

ae 

o/ 

? 63 

! 33 

45 

<radical> 
f 102 

<DELTA> 

< < 

> > 

blank 32 

A' 

A~ 

O- 

OE 

oe 

45 

45 

' 39 

' 39 

' 39 

' 39 

<divided by> 

< > 

ye 

YE 

/ 47 

o 111 

(continued) 

Macintosh to ProDOS transliterations E-l 1 



One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

< 

220 

< 

60 

< 

60 

> 

221 

> 

62 

> 

62 

fi 

222 

f 

102 

fi 


fl 

223 

f 

102 

fl 


* 

224 

1 

124 

1 = 



225 

• 

42 



» 

226 

1 

44 

l 

44 

n 

227 

1 

44 

t 1 


%o 

228 

% 

37 

% 

37 

A 

229 

A 

65 

AA 


E 

230 

E 

69 

EA 


A 

231 

A 

65 

A' 


E 

232 

E 

69 

E" 


E 

233 

E 

69 

E' 


i 

234 

I 

73 

V 


! 

235 

I 

73 

IA 


I 

236 

I 

73 

I" 


i 

237 

I 

73 

r 


6 

238 

O 

79 

O' 


6 

239 

O 

79 

OA 


ft 

240 

a 

97 

<Apple> 


0 

241 

O 

79 

O' 


0 

242 

u 

85 

U' 


u 

243 

u 

85 

UA 


u 

244 

u 

85 

IT 


1 

245 

i 

105 

i 

105 


246 

A 

94 

A 

94 

n 

247 

- 

126 

- 

126 

~ 

248 

- 

45 

- 

45 


249 

I 

44 

» 

44 


250 

• 

42 

• 

42 


251 

• 

42 

• 

42 

t 

252 

l 

44 

> 

44 


Macintosh to ProDOS: British English 

This transliteration is used only for British English. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the character listed. 


Source 

Source 

One to single character 
Destination Destination 

One to multiple characters 
Destination Destination 

character 

value 

character 

value 

character value 

£ 

163 

£ 

35 063 on GS) 

<pound> 
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Macintosh to ProDOS: Danish 

This transliteration is used only for Danish. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 


One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

A 

129 

A 

93 (129 on GS) 

A 

93 (129 on GS) 

4 

140 

4 

125 (140 on GS) 

4 

125 (140 on GS) 

0 

161 

o 

111 

<grader> 


<t 

162 

c 

99 

<cent> 


£ 

163 

L 

76 

<pund> 


• 

165 

* 

42 

* 

42 

<f 

166 

P 

80 

Pg 


8 

167 

s 

115 

ss 


* 

173 

# 

35 

# 

35 

A 

174 

/E 

91 (174 on GS) 

/£ 

91 (174 on GS) 

0 

175 

0 

92 (175 on GS) 

0 

92 (175 on GS) 

OO 

176 

- 

45 

<uendelig> 


11 

181 

m 

109 

<my> 


3 

182 

d 

100 

<delta> 


n 

184 

P 

80 

<PI> 


it 

/ 

185 

P 

112 

<pi> 


186 

S 

83 

<integralet> 


a 

189 

O 

79 

<OMEGA> 


X 

190 

as 

123 090 on GS) 

as 

123 (190 on GS) 

0 

191 

0 

124 (191 on GS) 

0 

124 (191 on GS) 

“I 

194 

- 

45 

. t 


V 

195 

V 

86 

<rod> 


a 

197 

- 

126 

-= 


A 

198 

D 

68 

<DELTA> 


A 

203 

A 

65 

A' 


+ 

214 

/ 

47 

<divideret med> 

0 

215 

< 

60 

< > 


* 

224 

t 

116 

t 

116 


225 

• 

42 

• 

42 

%0 

228 

% 

37 

%o 



Macintosh to ProDOS: Dutch and Flemish 

This transliteration is used only for Dutch and Flemish. It is the same as the U.S. 
English Macintosh to ProDOS transliteration except for the characters listed. 




One to single character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination Destination 

character 

value 

character 

value 

character value 


172 


126 (172 on GS) 


O 

l6l 

o 

111 

<graden> 


162 

c 

99 

<cent> 

£ 

163 

L 

76 

<pond> 

OO 

f 

176 

% 

37 

<oneindig> 

J 

1 

186 

S 

83 

<integraalteken> 

V 

195 

V 

118 

<wortelteken> 

+ 

214 

/ 

47 

<gedeeld door> 
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Macintosh to ProDOS: Finnish 


This transliteration is used only for Finnish. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 


Source 

Source 

One to single character 
Destination Destination 

One to multiple characters 
Destination Destination 

character 

value 

character 

value 

character value 

A 

128 

A 

91 (128 on GS) 

A" 

A 

129 

A 

93 029 on GS) 

AA 

6 

133 

6 

92 (133 on GS) 

O" 

a 

138 

a 

123 038 on GS) 

a" 

a 

140 

4 

125 (140 on GS) 

aa 

6 

154 

6 

124 (154 on GS) 

o" 

O 

161 

o 

111 

<aste> 

<t 

162 

c 

99 

<sentti> 

£ 

163 

L 

76 

<punta> 

oo 

176 

% 

37 

<aareton> 

1 

186 

S 

83 

<integraali> 

V 

195 

V 

118 

<juuri> 

+ 

214 

/ 

47 

<jakomerkki> 


Macintosh to ProDOS: French 

This transliteration is used only for French, Canadian French, and Swiss French. It is 
the same as the U.S. English Macintosh to ProDOS transliteration except for the 
characters listed. 




One to single character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination Destination 

character 

value 

character 

value 

character value 

4 

136 

4 

64 (136 on GS) 

a' 

9 

141 

9 

92 (141 on GS) 

c, 

6 

142 

e 

123 (142 on GS) 

e 1 

6 

143 

6 

125 (143 on GS) 

e' 

u 

157 

u 

124 (157 on GS) 

u' 

O 

l6l 

O 

91 (161 on GS) 

<degr6s> 

£ 

163 

£ 

35 (163 on GS) 

<livre> 

§ 

164 

§ 

93 (164 on GS) 

$ 36 

'■ 

172 

*• 

126 (172 on GS) 

. . 

oo 

176 

% 

37 

<infini> 

I 

183 

S 

83 

<sigma> 

J 

186 

S 

83 

<int£grale> 

Q 

189 

o 

79 

<om6ga> 

V 

195 

V 

118 

<racine> 

A 

198 

d 

100 

<delta> 

+ 

214 

/ 

47 

<divis6 par> 
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O' >• > # D *“ ‘M ! ft « c; oi a » » « O 0= 'Z 1 > ! 


Macintosh to ProDOS: German 


This transliteration is used only for German and Swiss German. It is the same as the 
U.S. English Macintosh to ProDOS transliteration except for the characters listed. 


Source 

character 


* 


n 


One to single character One to multiple characters 


Source 

Destination 

Destination 

Destination 

Destination 

value 

character 

value 

character 

value 

128 

A 

91 (128 on GS) 

A" 


132 

N 

78 

N- 


133 

6 

92 (133 on GS) 

O" 


134 

u 

64 (134 on GS) 

U" 


138 

a 

123 (138 on GS) 

a" 


139 

a 

97 

a- 


150 

n 

110 

n- 


154 

5 

124 (154 on GS) 

o" 


155 

o 

111 

o- 


159 

li 

125 (159 on GS) 

u" 


161 

o 

111 

<Grad> 


162 

c 

99 

<Cents> 


163 

L 

76 

<Pfund> 


164 

S 

93 (164 on GS) 

$ 

36 

167 

8 

126 (167 on GS) 

B 

66 

176 

% 

37 

<Unendlich> 

183 

S 

83 

<Sigma> 


186 

S 

83 

<Integral> 


189 

o 

79 

<Omega> 


195 

V 

86 

<Wurzel> 


197 

= 

61 

-= 


198 

d 

100 

<Delta> 


204 

A 

65 

A- 


205 

O 

79 

O- 


214 

/ 

47 

<geteilt durch> 

224 

/ 

124 

- = 


247 

- 

45 

- 

45 


Macintosh to ProDOS transliterations 
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Macintosh to ProDOS: Italian 


This transliteration is used only for Italian. It is the same as the U.S. English Macintosh 
to ProDOS transliteration except for the characters listed. 




One to single character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

A 

129 

A 

65 

A 0 


N 

132 

N 

78 

N- 


a 

136 

A 

123 036 on GS) 

i 

123 036 on GS) 

a 

139 

a 

97 

a- 


A 

140 

a 

97 

a° 


9 

141 

9 

92 (141 on GS) 

? 

92 (141 on GS) 

e 

142 

€ 

93 042 on GS) 

e 

93 (142 on GS) 

£ 

143 

S 

125 (143 on GS) 


125 (143 on GS) 

i 

147 

1 

126 (147 on GS) 

i 

126 (147 on GS) 

n 

150 

n 

110 

n- 


6 

152 

6 

124 (152 on GS) 

d 

124 (152 on GS) 

o 

155 

o 

111 

o- 


u 

157 

u 

96 (157 on GS) 

u 

96 (157 on GS) 

t 

160 

+ 

43 

+ 

43 

o 

161 

o 

91 (161 on GS) 

O 

91 (161 on GS) 


162 

C 

99 

<centesimi> 

£ 

163 

£ 

35 063 on GS) 

£ 

35 (163 on GS) 

5 

164 

S 

64 (164 on GS) 

§ 

64 (164 on GS) 


166 

P 

80 

PP 


® 

168 

R 

82 

(R) 


© 

169 

C 

67 

(C) 


TM 

170 

T 

84 

TM 


* 

173 

= 

61 

< > 


oo 

176 

% 

37 

<infinito> 


p 

181 

u 

117 

m 

109 

d 

182 

d 

100 

<DELTA> 


n 

184 

P 

80 

<P-greco> 


n 

185 

P 

112 

<p-greco> 


s 

186 

S 

83 

<integrale> 


V 

195 

V 

118 

<radice> 


as 

197 

= 

61 

.= 


A 

204 

A 

65 

A- 


6 

205 

O 

79 

O- 


- 

209 

- 

45 

-- 


y 

216 

y 

121 

y" 


Y 

217 

Y 

89 

Y" 


* 

224 

+ 

43 

++ 


t 

226 

i 

39 

i 

39 

n 

227 

i 

39 

i 

39 

%0 

228 

% 

37 

%o 


E 

233 

E 

69 

E' 


i 

237 

I 

73 

I' 


* 

240 

A 

65 

<Apple> 


6 

241 

O 

79 

O' 


u 

244 

U 

85 

U' 



249 

» 

44 

1 

39 


250 

* 

42 


46 


251 

* 

42 

o 

91 (161 on GS) 
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Macintosh to ProDOS: Norwegian 

This transliteration is used only for Norwegian. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 


One to single character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination Destination 

character 

value 

character 

value 

character value 

A 

129 

A 

93 (129 on GS) 

AA 

A 

140 

A 

125 (140 on GS) 

aa 

o 

l6l 

o 

111 

<grader> 

<t 

162 

c 

99 

<cent> 

£ 

163 

L 

76 

<pund> 

/E 

174 

/£ 

91 (174 on GS) 

AE 

0 

175 

0 

92 (175 on GS) 

O/ 

oo 

J 

176 

% 

37 

<uendelig> 

186 

S 

83 

<integraltegn> 

as 

190 

as 

123 (190 on GS) 

ae 

0 

191 

0 

124 (191 on GS) 

o/ 

V 

195 

V 

118 

<kvadratrot> 

+ 

214 

/ 

47 

<delt p> 


Macintosh to ProDOS: Spanish 

This transliteration is used only for Spanish. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 




One to single character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

N 

132 

N 

92 (132 on GS) 

N~ 


9 

141 

9 

125 (141 on GS) 

c, 


n 

150 

n 

124 (150 on GS) 

n~ 


o 

161 

O 

123 (161 on GS) 

<grados> 


C 

162 

C 

99 

<centimos> 


£ 

163 

£ 

35 (163 on GS) 

<libra> 


§ 

164 

s 

64 (164 on GS) 

$ 

36 

oo 

176 

% 

37 

<infinito> 


i 

192 

i 

93 (192 on GS) 

? 

63 

i 

193 

i 

91 (193 on GS) 

! 

33 

+ 

214 

/ 

47 

<dividido por> 
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Macintosh to ProDOS: Swedish 


This transliteration is used only for Swedish. It is the same as the U.S. English 
Macintosh to ProDOS transliteration except for the characters listed. 


Source 

Source 

One to single character 
Destination Destination 

One to multiple characters 
Destination Destination 

character 

value 

character 

value 

character value 

A 

128 

A 

91 (128 on GS) 

A" 

A 

129 

A 

93 (129 on GS) 

AA 

6 

133 

O 

92 (133 on GS) 

O" 

a 

138 

a 

123 038 on GS) 

a" 

a 

140 

4 

125 (140 on GS) 

aa 

o 

154 

o 

124 (154 on GS) 

o" 

O 

161 

o 

111 

<grader> 

<t 

162 

C 

99 

<cent> 

£ 

163 

L 

76 

<pund> 

oo 

176 

% 

37 

<oandlighet> 

I 

183 

S 

83 

<sigma> 

V 

195 

V 

118 

<rot> 

A 

198 

d 

100 

<delta> 

+ 

214 

/ 

47 

<dividerat med> 
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ProDOS to Macintosh transliterations 

For all members of the Apple n family of computers other than the Apple IIGS, there 
are 12 characters in the character set that vary from country to country. The ASCII 
codes for these 12 characters are the same in all countries, but there are differences in 
the actual characters. The cables in this section list these 12 characters for each 
country. All others characters are unchanged by transliteration; for example, c in a 
ProDOS source file remains c after it has been transliterated. 

One-character-to-multiple-character transliterations are not available for ProDOS to 
Macintosh translators. 


ProDOS to Macintosh: U.S. English 

This TProc is used for U.S. English as well as for Australian English. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

36 

$ 

36 

9 

64 

9 

64 

[ 

91 

[ 

91 

\ 

92 

\ 

92 

] 

93 

1 

93 

A 

94 

A 

94 


96 


96 

{ 

123 

{ 

123 

1 

124 

1 

124 

} 

125 

} 

125 

- 

126 

- 

126 


ProDOS to Macintosh: British English 

This transliteration is used only for British English. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

£ 

35 (163 on GS) 

£ 

163 

$ 

36 

$ 

36 

9 

64 

9 

64 

[ 

91 

l 

91 

\ 

92 

\ 

92 

1 

93 

] 

93 

A 

94 

A 

94 


96 


96 

{ 

123 

{ 

123 

1 

124 

1 

124 

} 

125 

} 

125 

- 

126 

~ 

126 


ProDOS to Macintosh transliterations 


E-l 9 



ProDOS to Macintosh: Danish and Norwegian 

This transliteration is used only for Danish and Norwegian. 

One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

36 

$ 

36 

9 

64 

9 

64 

A 

91 (174 on GS) 

A 

174 

0 

92 (175 on GS) 

0 

175 

A 

93 (129 on GS) 

A 

129 

A 

94 

A 

94 


96 


96 

ae 

123 (190 on GS) 

ae 

190 

0 

124 (191 on GS) 

0 

191 

i 

125 (140 on GS) 

i 

140 

- 

126 

~ 

126 


ProDOS to Macintosh: 

Dutch and Flemish 

This transliteration is used only for Dutch and Flemish. 



One to closest character 

Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

36 

$ 

36 

9 

64 

9 

64 

[ 

91 

[ 

91 

\ 

92 

\ 

92 

] 

93 

1 

93 

A 

94 

A 

94 


96 


96 

{ 

123 

{ 

123 

1 

124 

1 

124 

} 

125 

} 

125 


126 (172 on GS) 

•* 

172 
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ProDOS to Macintosh: Finnish 

This transliteration is used only for Finnish. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

36 

$ 

36 

@ 

64 

@ 

64 

A 

91 (128 on GS) 

A 

128 

6 

A 

92 (133 on GS) 

6 

133 

93 (129 on GS) 

A 

129 

A 

94 

A 

94 


96 


96 

a 

123 (138 on GS) 

a 

138 

6 

124 (154 on GS) 

6 

154 

4 

125 (140 on GS) 

4 

140 

~ 

126 

- 

126 


ProDOS to Macintosh: French 

This transliteration is used for French, Canadian French, and Swiss French. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

£ 

35 (163 on GS) 

£ 

163 

$ 

36 

$ 

36 

4 

64 (136 on GS) 

4 

136 

O 

91 (161 on GS) 

O 

l6l 

? 

92 (141 on GS) 

9 

141 

§ 

93 064 on GS) 

§ 

164 

A 

94 

A 

94 


96 


96 

e 

123 (142 on GS) 

6 

142 

u 

124 (157 on GS) 

u 

157 

6 

125 (143 on GS) 

6 

143 


126 (172 on GS) 

•• 

172 
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ProDOS to Macintosh: German 

This transliteration is used only for German and Swiss German. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

36 

$ 

36 

§ 

64 (164 on GS) 

§ 

164 

A 

91 (128 on GS) 

A 

128 

6 

92 (133 on GS) 

6 

133 

u 

93 (134 on GS) 

0 

134 

A 

94 

A 

94 


96 

* 

96 

a 

123 (138 on GS) 

a 

138 

6 

124 (154 on GS) 

6 

154 

ii 

125 (159 on GS) 

ii 

159 

13 

126 (167 on GS) 

13 

167 


ProDOS to Macintosh: 

Italian 


This transliteration is used only for Italian. 

One to closest character 

Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

£ 

35 (163 on GS) 

£ 

163 

$ 

36 

$ 

36 

5 

64 (164 on GS) 

§ 

164 

o 

91 (161 on GS) 

O 

161 

9 

92 (141 on GS) 

9 

141 

€ 

93 (142 on GS) 

€ 

142 

A 

94 

A 

94 

U 

96 (157 on GS) 

U 

157 

i 

123 (136 on GS) 

i 

136 

6 

124 (152 on GS) 

6 

152 

6 

125 (143 on GS) 

6 

143 

1 

126 (147 on GS) 

i 

147 
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ProDOS to Macintosh: Spanish 

This transliteration is used only for Spanish. 

One to closest character 

Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

£ 

35 (163 on GS) 

£ 

163 

$ 

36 

$ 

36 

§ 

64 (164 on GS) 

5 

164 

i 

N 

91 (193 on GS) 

i 

193 

92 (132 on GS) 

N 

132 

i 

93 (192 on GS) 

i 

192 

A 

94 

A 

94 


96 


96 

o 

123 (161 on GS) 

o 

l6l 

n 

124 (150 on GS) 

n 

150 

9 

125 (141 on GS) 

S 

141 

- 

126 

- 

126 


ProDOS to Macintosh: 

Swedish 


This transliteration is used only for Swedish. 




One to closest character 

Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

% 

36 

$ 

36 

@ 

64 

@ 

64 

A 

91 (128 on GS) 

A 

128 

O 

92 (133 on GS) 

6 

133 

A 

93 (129 on GS) 

A 

129 

A 

94 

A 

94 


96 


96 

a 

123 (138 on GS) 

a 

138 

6 

124 (154 on GS) 

d 

154 

4 

125 (140 on GS) 

4 

140 

- ' 

126 

~ 

126 
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ProDOS to MS-DOS transliterations 

For all members of the Apple II family of computers other than the Apple IIGS, there 
are 12 characters in the character set that vary from country to country. The ASCII 
codes for these 12 characters are the same in all countries, but there are differences in 
the actual characters. The tables in this section list these 12 characters for each 
country. All others characters are unchanged by transliteration; for example, c in a 
ProDOS source file remains c after it has been transliterated. 

One-character-to-multiple-character transliterations are not available for ProDOS to 
MS-DOS translators. 


ProDOS to MS-DOS: U.S. English 

This TProc is used for U.S. English as well as for Australian English. 


• One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

36 

$ 

36 

9 

64 

9 

64 

[ 

91 

t 

91 

\ 

92 

\ 

92 

1 

93 

1 

93 

A 

94 

A 

94 


96 


96 

{ 

123 

{ 

123 

1 

124 

1 

124 

} 

125 

} 

125 

- 

126 

- 

126 


ProDOS to MS-DOS: British English 

This transliteration is used only for British English. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

£ 

35 063 on GS) 

£ 

156 

$ 

36 

$ 

36 

9 

64 

9 

64 

[ 

91 

[ 

91 

\ 

92 

\ 

92 

] 

93 

1 

93 

A 

94 

A 

94 

' 

96 


96 

{ 

123 

{ 

123 

1 

124 

1 

124 

} 

125 

} 

125 

- 

126 

~ 

126 
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ProDOS to MS-DOS: Danish and Norwegian 

This transliteration is used only for Danish and Norwegian. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

36 

$ 

36 

® 

64 

@ 

64 

/E 

91 (174 on GS) 

VE 

146 

0 

92 (175 on GS) 

0 

157 

A 

93 (129 on GS) 

A 

143 

A 

94 

A 

94 


96 


96 

as 

123 (190 on GS) 

as 

145 

0 

124 (191 on GS) 

0 

155 

4 

125(140 on GS) 

4 

134 

- 

126 

- 

126 


ProDOS to MS-DOS: Dutch and Flemish 

This transliteration is used only for Dutch and Flemish. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

36 

$ 

36 

@ 

64 

9 

64 

[ 

91 

[ 

91 

\ 

92 

\ 

92 

] 

93 

1 

93 

A 

94 

A 

94 

' 

96 

X 

96 • 

{ 

123 

{ 

123 

1 

124 

1 

124 

} 

125 

} 

125 


126 (172 on GS) 

- 

126 
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ProDOS to MS-DOS: Finnish 

This transliteration is used only for Finnish. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

36 

$ 

36 

@ 

64 

@ 

64 

A 

91 (128 on GS) 

A 

142 

O 

92 (133 on GS) 

O 

153 

A 

93 (129 on GS) 

A 

143 

A 

94 

A 

94 


96 


96 

a 

123 (138 on GS) 

a 

132 

6 

124 (154 on GS) 

o 

148 

4 

125 (140 on GS) 

4 

134 

~ 

126 

~ 

126 


ProDOS to MS-DOS: French 

This transliteration is used for French, Canadian French, and Swiss French. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

£ 

35 (163 on GS) 

£ 

156 

$ 

36 

$ 

36 

4 

64 (136 on GS) 

4 

133 

o 

91 (161 on GS) 

O 

248 

9 

92 (141 on GS) 

9 

135 

S 

93 (164 on GS) 

$ 

36 

A 

94 

A 

94 


96 


96 

6 

123 (142 on GS) 

6 

130 

u 

124 (157 on GS) 

u 

151 

6 

125 (143 on GS) 

g 

138 


126 (172 on GS) 

~ 

126 
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ProDOS to MS-DOS: German 

This transliteration is used only for German and Swiss German. 

One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

# 

35 

# 

35 

$ 

3 6 

$ 

36 

§ 

64 (164 on GS) 

$ 

36 

A 

91 (128 on GS) 

A 

142 

6 

92 (133 on GS) 

O 

153 

u 

93 (134 on GS) 

U 

154 

A 

94 

A 

94 


96 


96 

a 

123 (138 on GS) 

a 

132 

6 

124 (154 on GS) 

6 

148 

ii 

125 (159 on GS) 

ii 

129 

13 

126 (167 on GS) 

8 

225 


ProDOS to MS-DOS: Italian 

This transliteration is used only for Italian. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

£ 

35 (163 on GS) 

£ 

156 

$ 

36 

$ 

36 

§ 

64 (164 on GS) 

$ 

64 

O 

91 (161 on GS) 

O 

248 

s 

92 (141 on GS) 

c 

135 

€ 

93 (142 on GS) 

€ 

130 

A 

94 

A 

94 

a 

96 (157 on GS) 

U 

151 

a 

123 (136 on GS) 

l 

133 

6 

124 (152 on GS) 

6 

149 

6 

125 (143 on GS) 

£ 

138 

1 

126 (147 on GS) 

i 

141 


ProDOS to MS-DOS transliterations 


E-27 



V* @ :< : 0 < 


ProDOS to MS-DOS: Spanish 

This transliteration is used only for Spanish. 


One to closest character 


Source 

Source 

Destination 

Destination 

character 

value 

character 

value 

£ 

35 (163 on GS) 

£ 

156 

S 

36 

$ 

36 

§ 

64 (164 on GS) 

$ 

36 

i 

91 (193 on GS) 

; 

173 

N 

92 (132 on GS) 

N 

165 

i 

93 (192 on GS) 

i 

168 

A 

94 

A 

94 


96 


96 

0 

123 (161 on GS) 

o 

248 

h 

124 (150 on GS) 

n 

164 

S 

125 (141 on GS) 

S 

135 


126 

- 

126 


ProDOS to MS-DOS: Swedish 


used only for Swedish. 


This transliteration is 


Source Source 

character value 

* 35 

36 
64 

91 028 on GS) 

92 (133 on GS) 

93 (129 on GS) 

94 
96 

a 123 (138 on GS) 

6 124 (154 on GS) 

4 125 (140 on GS) 

126 


One to closest character 
Destination Destination 


character value 

* 35 

$ 36 

@ 64 

A 142 

O 153 

A 143 

a 94 

96 

a 132 

5 148 

4 134 

126 
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MS-DOS to ProDOS transliterations 

The following tables list the transliterations from an MS-DOS character set to the 
corresponding ProDOS character set. 


MS-DOS to ProDOS: U.S. English 

This TProc is used for U.S. English as well as for Australian English. 


One to closest character 


One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

c 

128 

C 

67 

c, 

ti 

129 

u 

117 

u" 

6 

130 

e 

101 

e' 

i 

131 

a 

97 

a A 

a 

132 

a 

97 

a" 

a 

133 

a 

97 

a' 

i 

134 

a 

97 

aa 

9 

135 

c 

99 

c, 

e 

136 

e 

101 

e A 

e 

137 

e 

101 

e" 

d 

138 

e 

101 

e' 

i 

139 

i 

105 

i" 

i 

140 

i 

105 

iA 

i 

141 

i 

105 

i' 

A 

142 

A 

65 

A" 

A 

143 

A 

65 

AA 

E 

144 

E 

69 

E' 

ae 

145 

a 

97 

ae 

/E 

146 

A 

65 

AE 

6 

147 

o 

111 

o A 

6 

148 

o 

111 

o" 

6 

149 

o 

111 

o' 

u 

150 

u 

117 

UA 

u 

151 

u 

117 

u' 

y 

152 

y 

121 

y" 

o 

153 

o 

79 

O'* 

u 

154 

u 

85 

U" 

<t 

155 

c 

99 

<cents> 

£ 

156 

L 

76 

<pound> 

¥ 

157 

Y 

89 

Y= 

Pts 

158 

P 

80 

Pt 

f 

159 

f 

102 

f- 

a 

160 

a 

97 

a 1 

i 

l6l 

i 

105 

i' 

6 

162 

o 

111 

o' 

u 

163 

u 

117 

u' 

n 

164 

n 

110 

n~ 

N 

165 

N 

78 

N~ 

a 

166 

a 

97 

a _ 

Q 

167 

o 

111 

o _ 

i 

168 

p 

63 

p 


Destination 

value 


63 
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One to closest character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

comer 

169 

- 

45 

1- 



170 

- 

45 

-1 


1/2 

171 

2 

50 

1/2 


1/4 

172 

4 

52 

1/4 


i 

173 

! 

33 

! 


■ 

174 

< 

60 

< < 


m 

175 

> 

62 

> > 


OO 

224 

a 

97 

a 

97 

IS 

225 

b 

98 

b 

98 

r 

226 

8 

103 

8 


7t 

227 

P 

112 

Pi 


s 

228 

S 

83 

<SIGMA> 


a 

229 

s 

115 

<sigma> 


M- 

230 

u 

117 

u 

117 

T 

231 

t 

116 

t 

116 

<6 

232 

o 

111 

<PHI> 


9 

233 

o 

111 

O- 


Q 

234 

U 

85 

<OMEGA> 


d 

235 

d 

100 

<delta> 


OO 

236 

* 

42 

<infinity> 


0 

237 

O 

79 

O/ 


e 

238 

C 

40 

<epsilon> 


n 

239 

u 

85 

U 


= 

240 

= 

61 

. 

61 

± 

241 

+ 

43 

+- 


> 

242 

> 

62 

> = 


< 

243 

< 

60 

< = 


/ 

244 

c 

40 

C 


J 

245 

) 

41 

) 


+ 

246 

/ 

47 

<divided by> 

S3 

247 

- 

45 

~ 


0 

248 

o 

111 

<degrees> 


• 

249 

o 

111 

• 



250 

. 

46 


46 

V 

251 

V 

86 

<radical> 


n 

252 

n 

110 

An 


2 

253 

2 

50 

A2 
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MS-DOS to ProDOS: British English 

This transliteration is used only for British English. It is the same as the U.S. En glis h 
MS-DOS to ProDOS transliteration except for the character listed. 




One to closest character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination Destination 

character 

value 

character 

value 

character value 

£ 

156 

£ 

35 056 on GS) 

<pound> 


MS-DOS to ProDOS: Danish 

This transliteration is used only for Danish. It is the same as the U.S. English MS-DOS 
to ProDOS transliteration except for the characters listed. 


One to closost character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

6 

130 

e 

101 

e 1 


a 

133 

a 

97 

a' 


1 

134 

4 

125 040 on GS) 

4 

125 (140 on GS) 

6 

138 

e 

101 

e' 


I 

141 

i 

105 

i' 


A 

143 

A 

93 029 on GS) 

A 

93 029 on GS) 

ae 

145 

ae 

123 090 on GS) 

as 

123 090 on GS) 

/E 

146 

JE 

91 074 on GS) 

/E 

91 074 on GS) 

6 

149 

o 

111 

o' 


a 

151 

u 

117 

u' 


0 

155 

0 

124 (191 on GS) 

0 

124 (191 on GS) 

£ 

156 

L 

76 

<pund> 


0 

157 

0 

92 (175 on GS) 

0 

92 (175 on GS) 

comer 

169 

- 

45 

! _ 


-1 

170 

- 

45 

. i 


a 

224 

a 

97 

<alfa> 


s 

225 

S 

115 

SS 


r 

226 

G 

71 

<GAMMA> 


K 

227 

P 

112 

<pi> 


I 

228 

S 

83 

<SIGMA> 


a 

229 

s 

115 

<sigma> 


\i 

230 

u 

117 

<my> 


T 

231 

t 

116 

<tau> 


O 

232 

F 

70 

<PHI> 


0 

233 

T 

84 

<THETA> 


a 

234 

O 

79 

<OMEGA> 


d 

235 

d 

100 

<delta> 


oo 

236 

* 

42 

<uendelig> 


0 

237 

0 

124 (191 on GS) 

0 

124 (191 on GS) 

e 

238 

e 

101 

<epsilon> 


n 

239 

A 

94 

<faslles> 


= 

240 

= 

61 

= = 


+ 

246 

/ 

47 

<divideret med> 

~ 

247 

~ 

45 

~ = 


0 

248 

o 

111 

<grader> 



249 

* 

242 

* 

242 

V 

251 

V 

86 

<rod> 
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MS-DOS to ProDOS: Dutch and Flemish 

This transliteration is used only for Dutch and Flemish. It is the same as the U.S. 
English MS-DOS to ProDOS transliteration except for the characters listed. 




One to closest character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination Destination 

character 

value 

character 

value 

character value 

<C 

155 

c 

99 

<cent> 

£ 

156 

L 

76 

<pond> 

OO 

236 

• 

42 

<oneindig> 

-h 

246 

/ 

47 

<gedeeld door> 

o 

248 

o 

111 

<graden> 

V 

251 

V 

86 

<wortelteken> 


MS-DOS to ProDOS: Finnish 

This transliteration is used for Finnish. It is the same as the U.S. English MS-DOS to 
ProDOS transliteration except for the characters listed. 




One to closest character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination Destination 

character 

value 

character 

value 

character value 

a 

132 

a 

123 038 on GS) 

a" 

4 

134 

4 

125 040 on GS) 

aa 

A 

142 

A 

91 028 on GS) 

A" 

A 

143 

A 

93 029 on GS) 

AA 

6 

148 

6 

124 (154 on GS) 

o" 

O 

153 

6 

92 (133 on GS) 

O" 

<t 

155 

c 

99 

<sentti> 

£ 

156 

L 

76 

<punta> 

<t> 

232 

o 

111 

<PII> 

OO 

236 

0 

42 

<aareton> 

+ 

246 

/ 

47 

<jakomerkki> 

o 

248 

o 

111 

<aste> 

V 

251 

V 

86 

<juuri> 
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MS-DOS to ProDOS: French 

This transliteration is used for French, Canadian French, and Swiss French. It is the 
same as the U.S. English MS-DOS to ProDOS transliteration except for the characters 


listed. 







One to closest character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination Destination 

character 

value 

character 

value 

character value 

i 

133 

i 

64 (136 on GS) 

a' 

9 

135 

? 

92 (141 on GS) 

c, 

6 

138 

£ 

125 (143 on GS) 

e 1 

u 

151 

u 

124 (157 on GS) 

u' 

& 

156 

£ 

35 (163 on GS) 

<livre> 

s 

228 

S 

83 

<sigma> 

a 

229 

s 

115 

<sigma> 

<0 

232 

o 

111 

<phi> 

Q 

234 

U 

85 

<omega> 

3 

235 

d 

100 

<delta> 

oo 

236 

• 

42 

<infini> 

+ 

246 

/ 

47 

<divise par> 

o 

248 

o 

111 

<degres> 

V 

251 

V 

86 

<racine> 


MS-DOS to ProDOS: German 


This transliteration is used for German and Swiss German. It is the same as the U.S. 
English MS-DOS to ProDOS transliteration except for the characters listed. 


Source 

Source 

One to closest character 
Destination Destination 

One to multiple characters 
Destination Destination 

character 

value 

character 

value 

character value 

ii 

129 

ii 

125 (159 on GS) 

u" 

a 

132 

a 

123 (138 on GS) 

a" 

e 

137 

e 

137 

e" 

A 

142 

A 

91 (128 on GS) 

A” 

5 

148 

o 

124 (154 on GS) 

o" 

O 

153 

6 

92 (133 on GS) 

O" 

U 

154 

u 

93 (134 on GS) 

U" 


155 

c 

99 

<Cents> 

£ 

156 

L 

76 

<Pfund> 

n 

164 

n 

110 

n- 

N 

165 

N 

78 

N- 

comer 

169 

- 

45 

1 “ 

“1 

170 

- 

45 

~ 1 

JS 

225 

13 

126 (167 on GS) 

B 66 

r 

226 

g 

103 

<gamma> 

T 

231 

t 

116 

<tau> 

9 

233 

o 

111 

<theta> 

£2 

234 

U 

85 

<Omega> 

OO 

236 

% 

37 

<Unendlich> 

e 

238 

( 

40 

<Epsilon> 

n 

239 

u 

85 

<intersection> 

+ 

246 

/ 

47 

<geteilt durch> 

ss 

247 

- 

45 

45 

O 

248 

o 

111 

<Grad> 

V 

251 

V 

86 

<Wurzel> 
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MS-DOS to ProDOS: Italian 

This transliteration is used only for Italian. It is the same as the U.S. English MS-DOS 
to ProDOS transliteration except for the characters listed. 


One to closest character One to multiple characters 


Source 

Source 

Destination 

Destination 

Destination 

Destination 

character 

value 

character 

value 

character 

value 

e 

130 

e 

93 (142 on GS) 

e 

93 (142 on GS) 

a 

133 

i 

123 036 on GS) 

a 

123 (136 on GS) 

a 

134 

a 

97 

a° 


9 

135 

9 

92 (141 on GS) 

9 

92 (141 on GS) 

e 

138 

e 

125 (143 on GS) 

6 

125 (143 on GS) 

i 

141 

1 

126 (147 on GS) 

1 

126 (147 on GS) 

A 

143 

A 

65 

A° 


6 

149 

6 

124 (152 on GS) 

6 

124 (152 on GS) 

u 

151 

u 

96 (157 on GS) 

u 

96 (157 on GS) 


155 

c 

99 

<centesimi> 


£ 

156 

£ 

35 (163 on GS) 

£ 

35 (163 on GS) 

f 

159 

f 

102 

f 


n 

164 

n 

110 

n- 


N 

165 

N 

78 

N- 


comer 

169 

- 

45 



“I 

170 

- 

45 



6 

225 

B 

66 

B 

66 

r 

226 

G 

71 

G 

71 

1C 

227 

P 

112 

<p-greco> 


a 

229 

s 

115 

<sigma> 


P 

230 

m 

109 

m 

109 

T 

231 

t 

116 

t 

116 

<I> 

232 

F 

70 

<phi> 


0 

233 

T 

84 

<TETA> 


ft 

234 

O 

79 

<omega> 


3 

235 

d 

100 

<DELTA> 


CO 

236 

% 

37 

<infinito> 


e 

s 

i 

238 

e 

101 

<epsilon> 


244 

f 

102 

<integrale> 


245 

i 

106 

J 


+ 

246 


58 



S3 

247 

= 

61 

== 


o 

248 

O 

91 (161 on GS) 

O 

91 (161 on GS) 

• 

249 

0 

111 

O 

111 


251 

V 

86 

<radice> 
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MS-DOS to ProDOS: Norwegian 

This transliteration is used only for Norwegian. It is the same as the U.S. English 
MS-DOS to ProDOS transliteration except for the characters listed. 




One to closest character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination Destination 

character 

value 

character 

value 

character value 

$ 

155 

c 

99 

<cens> 

£ 

156 

L 

76 

<pund> 

<D 

232 

o 

111 

<PI> 

OO 

236 

• 

42 

<uendelig> 

G 

238 

( 

40 

<ypsilon> 

+ 

246 

/ 

47 

<delt p> 

o 

248 

o 

111 

<grader> 

V 

251 

V 

86 

<kvadratrot> 


MS-DOS to ProDOS: Spanish 

This transliteration is used only for Spanish. It is the same as the U.S. English MS-DOS 
to ProDOS transliteration except for the characters listed. 


Source 

Source 

One to closest character 

Destination Destination 

One to multiple characters 
Destination Destination 

character 

value 

character 

value 

character value 

9 

135 

9 

125 (141 on GS) 

c, 

<t 

155 

c 

99 

<centimos> 

£ 

156 

£ 

35 (163 on GS) 

<libra> 

n 

164 

n 

124 (150 on GS) 

n~ 

N 

165 

N 

92 (132 on GS) 

N~ 

i 

168 

d 

93 (192 on GS) 

? 63 

i 

173 

i 

91 (193 on GS) 

! 

OO 

236 


42 

<infinito> 

+ 

246 

/ 

47 

<dividido por> 

o 

248 

o 

123 (l6l on GS) 

<grados> 
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MS-DOS to ProDOS: Swedish 


This transliteration is used only for Swedish. It is the same as the U.S. English MS-DOS 
to ProDOS transliteration except for the characters listed. 




One to closest character 

One to multiple characters 

Source 

Source 

Destination 

Destination 

Destination Destination 

character 

value 

character 

value 

character value 

a 

132 

a 

123 (138 on GS) 

a" 

a 

134 

4 

125 (140 on GS) 

aa 

A 

142 

A 

91 (128 on GS) 

A" 

A 

143 

A 

93 (129 on GS) 

AA 

6 

148 

o 

124 (154 on GS) 

o" 

6 

153 

6 

92 (133 on GS) 

O" 

4 

155 

c 

99 

<cent> 

£ 

156 

L 

76 

<pund> 

2 

228 

S 

83 

<sigma> 

a 

229 

S 

115 

<sigma> 

O 

232 

o 

111 

<fi> 

a 

235 

d 

100 

<delta> 

oo 

236 

♦ 

42 

<oandlighet> 

+ 

246 

/ 

47 

<dividerat med> 

o 

248 

o 

111 

<grader> 

V 

251 

V 

86 

<rot> 
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Glossary 


active: For translators, one that is available for 
use. Active translators are checked in translator 
menus or, in the case of default translators, 
marked with a diamond to the left of their menu 
items to indicate that they are always active. 

activate: To make a previously unavailable 
translator available by selecting its menu item. 

Apple File Exchange document: A document 
used to store both translator settings and status 
information for translators. Users can save the 
current settings and status by selecting the Save 
Settings As menu item; they can retrieve saved 
settings by selecting the Restore Settings From 
menu item. 

Apple PC 5.25 Drive: A disk drive for Apple 
computers that can read and write MS-DOS disks. 

available: For translators, one that is contained in 
the Apple File Exchange folder. Available 
translators can appear in Apple File Exchange 
menus.- 

character set: The entire set of characters that 
can be either shown on a monitor or used to code 
computer instructions. 

country code: A code that identifies the country 
for which a country-specific feature or resource is 
intended. For a complete description of country 
codes, see “The International Utilities Package” 
chapter in Volume I of Inside Macintosh. 

deactivate: To make a previously available 
translator unavailable by selecting its menu item. 

default translator: A translator that makes a bit- 
for-bit copy of a file. 

destination country: The country for which a 
transliterated file is intended. 


error message: A message displayed or printed 
to tell you of an error or problem in the execution 
of a program or in your communication with the 
system. 

file format: The internal structure of a file. 

file system: That part of an operating system that 
performs operations related to files, such as 
writing, reading, deleting, and getting 
information about files. 

file-system resource: An Apple File Exchange 
resource that provides an interface to a file system. 

file-system routine: A routine for performing a 
file-system operation. 

foreign file system: Any file system other than 
the one for the Macintosh. 

general-purpose translator: A translator that 
can convert a file format used by a wide variety of 
applications to another widely used format. 

import: To move a translator from one menu to 
another. 

inactive: For translators, one that is not available 
for use. 

Macintosh n PC Drive Card: A removable 
printed-circuit board that allows an Apple PC 5.25 
Drive to be connected to a Macintosh II. 

Macintosh Programming Workshop (MPW): A 
set of professional software development tools for 
the Macintosh. 

Macintosh SE Bus PC Drive Card: A removable 
printed-circuit board that allows an Apple PC 5.25 
Drive to be connected to a Macintosh SE. 

message: A request for an operation sent from 
Apple File Exchange to a translator. 






modal: Refers to a dialog box in which the user 
must click a button before doing anything else. 

source country: Before a file is transliterated, the 
country for which it is intended. 

special-purpose translator: A translator that is 
used when the format of either the source or 
destination file is used by a limited range of 
applications. Nearly all translators that are not 
written by Apple are special-purpose translators. 

status flags: Bits that identify the current state of a 
translator. 

TProc: A routine for transliterating files provided 
by Apple File Exchange or another application. 

TProc family: A set of TProcs whose source 
country is the same. 

translation parameter block: A parameter 
block whose fields are used for moving 
information to and from translators. 


translator: A routine invoked by Apple File 
Exchange when moving files. All translators, with 
the exception of default translators, convert a file 
from one format to another. 

translator file: A resource file that contains 
translators. 

translator menu: Any of the Apple File 
Exchange menus from which users select 
translators. 

transliterate: To convert characters to equivalent 
characters in another character set. 

transliteration procedure: Any procedure, such 
as a TProc, that performs a transliteration. 

unavailable: For translators, one that is not 
contained in the Apple File Exchange folder. 
Unavailable translators cannot appear in Apple 
File Exchange menus. 

User Log: A record kept by Apple File Exchange 
of file translations and messages. 
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